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abs “absolute Value TOUlIne wicsiceeiadnseiiinicdanneds 1-1 
abs() | - absolute value Of inte ger... esecssessssssssssesessesseesssssessesseees 1-1 
accept ) - ACCept CONNECTION FLOM SOCKE ...ccescesscsssssessesseeressssessessesseess 1-354 
acu ) - return contents Of ACW register... ssssssessescecsssssessssseeee 1-508 
arptabShou ) - display known ARP eMtries......ccescsscesesseesssesesseseseeeeeneneeees 1-246 
bLib - buffer manipulation Hbrary 00.0... essesssssssssssssesssssessessseeseeees 1-2 
bemp{ ) - compare One buffer to another... secssessssssessssssscssesenensens 1-3 . 
bcopyBytes{ ) - copy one buffer to another one byte at a time ......... essen 1-6 
bcopyLongs{ ) - copy one buffer to another one long word at a time......... 1-7 
bcopyWords( ) - copy one buffer to another one word at a time ...............06 1-7 
bcopy() - COPY One buffer to AMOCHET 0.0... secssessecsesesecseseessosseesesesesseeees 1-6 
bdall() = Clete: all DLC AK POUAS accshsssacstiakdaniedh ate cis seestensad ecedeantdentea ccs tectes 1-28 
bd() =(CelOe DRCAK DOUG siss5cc css vesdecncthsisnyes eesssssveeuiteianiusiesecssienusecigeaanas 1-28 
b{) - Set or display breakpoint... sessssessessscsecessseseseseesesneees 1-26 
bfillBytes( ) - fill buffer with specified character one byte at a time....... 1-9 
bfill( ) - fill buffer with specified CHATacter .......csessssesesssseseesenesesseeees 1-8 
bind( ) = bind Name tO SOCKEL nits 2s iesuniiniancane 1-352 
bindresvuport{ ) - bind socket to privileged IP port... ssssssesecssssecessseeeesees 1-269 
binvert ) - invert order of bytes in DUffEL ........sccccssssssssssessssesessesecssseesssees 1-4 
bootBpAnchorExtract( ) - extract backplane address from device field... eee 1-18 
bootChange( ) SCNANGE DOOL UNG sx tagecesscntinntsiieednaciandoataanaadan cane 1-484 
bootCo - system configuration module for boot ROMG............sss0+ 1-10 
bootinit - ROM initialization module..u.. ec sssessssseseseseseeuseeseeeceeseeees 1-11 
bootLib - boot ROM subroutine Bbrarry os cssssctecseesseeesseeeeeenee 1-13 
bootNetmaskExtract{ ) - extract netmask field from Internet addres5...............ccc000 1-17 
bootParamsPrompt() - prompt for boot line parameters... scsssessesseeeseeceeeneee 1-16 
bootParamsShou{) _— - display boot line parameters... eessessseseescesceeseccnscseeseees 1-16 
bootStringToStruct{) — - interpret boot parameters from boot line... eee eee Fs Us, 
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bootStructToString,) — - construct boot lime... es esssssesecsessssssncssssscsssssesscsseesssssseveee ce 1-15 
bpInit{ ) - initialize backplame anchor .............sssssssssssssssessedbecsessssasssseess 1-127 
bpShou ) - show information about backplane network..........ce0++ 1-128 
bpattach( ) - attach bp interface to metwoOrk........cccsssssessesssssecsersesneseesseesseeee 1-127 
bswap( ) SS WAD DULCIS css vietaastnvccdsnctertes ar aeainscsace uti einy aie! 1-4 
bzero{ ) @ ZetO OUl DUMeL scsciciedchnstadvek entetendesenlaiedacadiancnsis 1-5 
cALib . —~C-language support routines... ssssscessecsssesssesssscenesssssees 1-19 
calloc{ ) ~ allocate space FOF ATTAY ........ssssessesssssessssssessesesessssessesossverscenseenes 1-225 
cd() - Change default directOry.........ecsscssssssssssssssssscessssssssssseesseees 1-494 
c() - continue from breakpoint... ssssssccsessessessesseeeessssassesseeees 1-29 
cfree() =free DIOCK Of MOMOLY iia ciesiectiestskecentccetinnceiandiens . 1-227 
chdir{ ) - Set current default pathn. i sesssessssessscsssssessseeeseaeeesees . 1-167 
checkStack( ) - print summary of each task’s stack USAC... ssssesseeseees . 1-488 
clearerr( ) | - reset error and end-of-file indicatoTs ..........cesscsstsscsteeeeeseee 1-385 
closedir{ ) S1CIOSE CINCCIOLY (iis s2iiits oc ae lia atti 1-38 
close{( ) CMOS A i Aaa etal aca gece cet de cede cat do ease eiasteht ceases 1-163 
compress | - general purpose file compression UEIitY «00.0.0... sssesssenseee 3-1 
connect, ) - iMitiate CONNECTION tO SOCKET... esecssecssesesesesecececeseeeseatenees 1-354 
copyStreams( ) - copy from/to specified StreaMs .........esscsssecesssersseseeseenesenees 1-497 
copy{) | - COpy in (or stdin) to OUt (OF SEAOUL) uo. eeresscessesseeesessssessssesecesenes 1-496 
creat{ ) CR AL PUNE oesesceseiit, teekcessectes secre ear tesatas asec eect treed cee 1-160 
cret{ ) - continue until return from current subroutine.................... 1-29 
ctypeLib - character classification and CONVeTSION MACTOS .........es000+ 1-21 
db ) set dala Drea point isesulcccesieiiteteGetntualarstanuimsaeaacn: 1-27 
_ dbgHelp ) - display debugging help Menu..........csssssesecsssesssssssseeseaneese 1-24 
dbglnit, ) - initialize debug package ........csesssessssssssesssssssssssssssssesssssssssssees 1-25 
dbgLib = GebUg eine facilites vcsssccisieciiiucieen desi esasaaticornendaieletts 1-22 
delete( ) SIAC LOCC TALE sissadecs sss scsacnsiaisaseccsstlesades a cecagins cootenieeeatl ates eee 1-161 
devs( ) - list all system-kKnOWM CeVICES.........cecsecssssntscnscecssnseneeseenseeseeene 1-504 
d() SIS DIA CNCEINON Yessy cea at ca nau seay adden to erceanes aseeencade 1-494 
dirLib - POSIX directory handling Bbrarry 0... es esseseseesceneenseneene 1-34 
diskFormat ) SPORTAL CLAS Ie sss csek cesses sts tccen ts ads ccesstes sacle sec ceeus becuse cbiaetevetanetb bens 1-498 
diskInit( ) - initialize file system OM DIOCK device on. eescecssscneesseesneesees 1-498 
dosFsConfiginit{ ) - initialize dosFs volume configuration structure ............... 1-53 
dosFsDateSet{ ) GOt CUITONE Cate c.s.cicccaeatviiissscnapdionescioniaieedin is 1-54 
dosFsDateTimeInstall( ) - install user-supplied date/time function ........ ee esceeeee 1-54 
dosFsDevInit{ ) - associate block device with dosFs file system functions. 1-55 
dosFslnit{ ) - prepare to use GOSFS HDrary .00..........ssessecssesseeseseesessescseneesees 1-56 
dosFsLib - MS-DOS media-compatible file system library.................. 1-40 
dosFsMkfs( ) - initialize device and create dosFs file system... sess 1-57 
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dosFsModeChange()  - modify mode of dosFs VOIUME .............ssssssssseessecesseessessnssseeee 1-58 
dosFsReadyChange() - notify dosFsLib of change in ready statuB..............ssesssseses 1-58 
dosFsTimeSet{ ) = SEt CULTORE ENG Sos cacsecsnesicecdecs teeta ase itaniove toeteiiedeets 1-59 
. dosFsVolUnmount() —-~ unmount GOSFS VOHIME ...........ssssscssscocssassscessesescecerscesssacassacecs 1-60 
dsm960Inst{ ) - disassemble i960 object COE...........ssscssssssssssescrsseesssessesesesesene 1-62 
dsm960Lib - Vx960/ 80960 disassemble’ ...........ccesssscesssscssesnessersssessseesesseeees 1-61 
enpattach( ) - attach enp interface to NEtWOTK............scssesssssecsssersessseeesesseeese 1-130 
errnoGef{) — - get error status value of Calling task .0.........ccssssssceseesceseeeees 1-65 
ermoLib PCTVOU SCALUS MDE ALY. cscasssielasisascusescctseuns uss cautasissocsueiss casssessestisia Gatuss 1-63 
errnoOfTaskGet( ) - get error status value of specified task... .sssssssssseseseeees 1-65 
errnoOfTaskSet{ ) - set error status value of specified task 0.0.0.0... cessssssesseescsesees 1-66 
errnoSet{ ) - set error status value of calling task.......... Seine 1-66 
etherAddrResolve{) — - resolve Ethernet address for given Internet address......... 1-72 
etherInputHookAdd() - add routine to receive all Ethernet input packets .............. 1-70 
etherLib - Ethernet raw I/O routines and QOOkKS...........sssssessecsecceensenees 1-68 
etherOutputHookAdd{ ) - add routine to receive all Ethernet output packets........... 1-71 
etherOutput{ ) - send packet on Ethernet interface 2.0.0... scesescssesesssseseeees 1-69 
exattach{ ) - attach ex interface to NEtWOTK...........cccscssscseseccsestsesecesssossseese 1-131 
exc960Lib - architecture-dependent exception handling: i960.............. 1-74 
excHookAdd{ ) - specify routine to be called with exceptions...........secscssees 1-78 
excInfoShow ) - display exception information..........cssecsssseccsscssesesensesseeeees 1-75 
excinit( ) - initialize exception handling package ............ssssscscssccssssseeees 1-77 
excLib - exception handling facilities... .ssesssessssssescssesssseeesseseeeees 1-76 
excNMIHookA dd{ ) - add hook routine to be called in event of NMI...............06 1-75 
excTask{ ) - handle task-level exceptions .0........ecsssesssccsscescssseseccsensensseeees 1-79 
excVecInit{ ) - initialize exception /interrupt VeCtOTS ..........eccecseesesecnceneesees 1-74 
exit{ ) MAE TAS eek cisaasrsas rtd estates isteancaee aint neaceasamy 1-422 
extract - conditionally extract files from archive... .esessecsesseeeeeees 3-3 
fclose( ) - empty stream buffers and close file 0... esscsscececesssoneees 1-372 
fdopen() - associate Stream With fd ou ssssssscecseseesssesseecseseecseestersereenees LOZ 2 
fdprintf() - print formatted string to specified fd... tsestessscneesees 1-83 
feof() - determine if end-of-file has beer read... ee eeeseeteeeenees 1-386 
ferror() - determine if error has occurred while reading or 
UTNE festa ais ae tet tes a eae tele eererted 1-386 
fflush() - write out any buffers on Output Stream... essessesesseeesee 1-374 
fgetc() - return next character in input Stream... seeccecestsccseeeees 1-373 
fgets() - read string from input StTeAM........ccccccsssscssssescscssnecsssscesssseessnes 1-373 
fileno{ ) : - get fd associated With Stream ........esecsssesseccensceeeeenecneeneceees 1-387 
fioFormatvV( ) - CONVETt fOrMAL SETI... ecssecsesetssesescescecenesecccnsneesesceesensenees 1-86 
fioLib =formatted 1/ O MDIAty wiccssaassactencsseasteisioceutteteeasosenecnteatenuietes 1-80 
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fioRdString{ ) - read string from file ... Ghee es teenie at ee deaeasent:, eR 
fioRead( ) - read buffer... suivante LOO 
floatInit{ ) - initialize floating- point V/ O support... Sc siecceaecttesaseuiteiaceagtc ods 1-91 
floatLib - floating-point formatting and scanning library.................._ 1-91 
fopen() SOUR STHOANT ONL GS a oasscaccssscssssi'scestsasosscscsntcsenntsacoastadesiseannseteate 1-374 
fppALib - floating-point support assembly language routines........._ 1-93 
fppLib | - floating-point support HDrary................sscvssscsserssssseeseseresesseeee 1-94 
fppProbe( ) - probe for presence oi floating-point support................ss00 1-96 
fppTaskRegsGet{ ) - get floating-point registers from task TCB.............sssssssssees 1-95 
fppTaskRegsSet{) —__- set floating-point registers Of task............c.scscssssssssssenesssseeees 1-96 
fppTaskRegsShou{) _ - display floating-point registers Of task ...........ssssssssssssssesseoeee 1-95 
fprintf{) - print formatted string to StrOAM.........sssseccssnsensssossesesesees 1-375 
fputc() - append character to Output StreaM..........ccsssesessssseesseesees 1-376 
fputs() - copy NULL-terminated string to output stream................ 1-376 
fread( ) - perform buffered Tead............sssssscsssesscesenssessasenesseessnsesoeeeseneeeess 1-377 
free() - free block Of MEMOTY ou... esesecesssessecesceeceassecesseeees Besos mreveaecasd! 1-226 
 freopen() - substitute named file in place of open stream ..............006 1-377 
fscanf() - read and convert characters from input SHEA ......seeeeseees 1-382 
fseek{ ) = FE POSIIONS IRE AIM 5 cal cesses eesasecs sd sovaesee cadacts dap sesescsbescabuscadeqssanpenscts 1-378 
fstat() - Zet file status infOrMatiOn 0.0.0.0... sssssssosesseseescsessccsessneeneseeees 1-38 
ftell() | - Feturn current Offset im STEAD ......c.sccssesssssesssescessseseecsnnesesneees 1-378 
ftpCommand( ) - send FTP command and get reply... ..osscsonsccsssscccsescserssecenees 1-99 
ftpDataConnGet ) - get completed FTP data COMMECTHON.........ccccsscsssesssesssssenseees 1-105 
ftpDataConnInit{ ) - initialize FTP data COMMECTION..........c.scssssssssesecsesssssessssecesssees 1-104 
ftpHookup{ ) : - get control connection to FTP server on specified host ... 1-103 
ftpLib - ARPA File Transfer Protocol Hbrary..........csscsssssscessecesssseees 1-98 
ftpLogin( ) - log in to remote FTP Servet ...........sssssescesecessseceecesecsecnecnseeee senses 1-104 
ftpReplyGet{ ) - get FTP command reply ...............00 Seiad aria eens 1-102 
ftpXfer( ) - imitiate transfer Via FTP .o...csssssssssssssssssssssssssssssssssssssssssessssoes 1-100 
ftpdDelete{ ) - clean up and finalize FTP server task o.0.........sssesessessseeeeee 1-108 
ftpdInit( ) ~ Imitialize FTP server task ........cssesssseceseseesesscsscsessssceseeesnesesees 1-108 
ftpdLib - ARPA File Transfer Protocol Server .0.......sssssssssssssssssenseeeesenee 1-106 
ftpdTask{ ) ~ FTP server daemon task...........ccccccssessssssscssscsssssscesscsecsssssceesoeees 1-107 
furite() - perfor buffered Write .......cssssssssssessssssessnscesseessessssseecneseesee 1-379 
getc() - return next character in input StPeEaM ......... ec eesssesssesseneeeees 1-388 
getchar\ ) - return next character in standard in stream............ccceceeees 1-387 
getcwd( ) - get current default Path ........csncrcssecssscsssevsasseeresnonorssseecseeasensosee 1-168 
gethostname( ) = get symbolic name of this MACHINE... sccssseseseeeeneeeseeeee 1-113 
getpeername( ) - get name Of Connected Peel... rescsecsscesessscsecsesserseessensseseeeee 1-360 
gets() - read string from standard in Stream ...........cccessssseseeseseeeees 1-379 
getsockname( ) EL SOCK OL TANG saccades cio as saa desea eat ataadtodaceste ian eeactatonts 1-359 
getsockopt{ ) = PEt SOCKEL OPUION Ss cisecssssoscsetsceascicdessstatiouees hedeoestasMipuseceastieaneets AA OO 
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getwd{ ) - get current default path ........sesccsccsccsecsnccceccsssececntecescescesceneenes 1-168 
getur ) - read next word (32-bit integer) from stream .............sscscesees 1-380 
help{ ) - print synopsis of selected TOUtINES.............eesseecesecacneesenseness 1-481 
h() - display (or set) shell NistOry ............sssssssssssssssessescasssssssceseeeeees 1-510 
hostAdd ) - add host to host table uu... esscesssssseceesececsesessenssereeeceseseacacees 1-110 
hostDelete{ ) - delete host from host table. .............cccssscscssssecesssersosesececcecscnees 1-111 
hostGetByAdadr{ ) - look up host in host table by Internet address.............s:0+ 1-112 
hostGetByName( ) - look up host in host table by mame. 0.0.0... ssessscssesseessessessseees 1-111 
hostLib - host table subroutine LDrary «00.0... ecssscsseccnssceseecsnsseccereeeees 1-109 
hostShour ) midis Play THOSE Calle etiaies seis choe iss east ie aay ic ettedee 1-112 
hostTolInit{ ) - initialize network host table 2.00... eesssscesccsscessceecseereeseeees 1-110 
htonl() - convert long (32 bit) from host to network byte order..... 1-392 
htons() - convert short (16 bit) from host to network byte 
0) 48 (2) Coe ern open” OPERONS ere a Pa erTET TANSEY ory vEE Or een ere re rere TT 1-393 
iam() - set remote uSer name ANd PaSSWOT ........sessecececeseseecesseneens 1-268 
icmpstatSkow ) - display statistics for ICMP... cccssssssssssessssesssesnsseanseessseesseess 1-243 
i(') - print summary of each task’s TCB .......sscsesssessessesecssseeees 1-489 
ifAddrGet ) - get Internet address of network interface ........ecsssessssseseee 1-116 
| ifAddrSet( ) - set interface address for network interface ...........eccceee 1-116 
ifBroadcastGet{ ) - get broadcast address for network interface ....... esses 1-118 
ifBroadcastSet{ ) - set broadcast address for network interface............ssssceesee 1-117 
ifDstAddrGet{ ) - get Internet address of point-to-point Pee®.......ececessereeese 1-119 
ifDstAddrSet{ ) - define address for other end of point-to-point link........... 1-118 
ifFlagChange( ) - change network interface fags... csessessceenssesecessesseeceeeee 1-120 
ifFlagGet{ ) - Zet Network interface FIA MS 0... essssssssseseceesscssseesesesseeees 1-122 
ifFlagSet{ ) - specify flags for network interface os eessscscecseceecseesseseeees 1-121 
ifLib - NetWOrk interface HDrAry uu... esscssseecssceseseeseeceseseensecneseeeceeees 1-115 
ifMaskGet{ ) - get subnet mask for network interface oe essscscssceeeessees 1-120 
ifMaskSet{ ) - define subnet for network interface ........ccssccsesssscessssseseeseess 1-119 
ifMetricGet( ) - get metric for netWOrk interface... essecssccsccssssscsseserereeess 1-123 
ifMetricSet{ ) - specify network interface hOp COUN... esessesssseeseesseseeens 1-122 
ifRoute Delete ) - delete routes associated with network interface................ 1-123 
ifShour ) - display attached network interfaces.............ssssesseeeee teats 1-242 
if - Vx960 & SunOS backplane drive... sessssessseessseseeeessesees 1-125 
if enp - CMC ENP 10/L Ethemet interface driver... csessesseees 1-130 
if_ex - Excelan EXOS 201/202 /302 Ethernet interface driver..... 1-131 
if In - LANCE Ethernet interface driver ........ccsesssssssessssseeesseessees 1-132 
if sl - serial line IP (SLIP) network interface driver... 1-134 
ifunit() - map interface name to interface structure pointer ............ 1-124 


inetLib - Internet address manipulation routines 2000... cssecsceseceeees 1-139 
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inet_addr( ) 
inet_Inaof() © 
inet_makeaddr_W) 


inet_makeaddr{ ) 


inet_netof( ) 
inet_netof_string() 
inet_network() 


inet_ntoa_D{) 
tnet_ntoa() 
tnetstatShow ) 


intALib 
intConnect( ) 
intContext{ ) 


intCount{ ) 
intHandlerCreate( ) 
intLevelSet{ ) 
intLib 
intLockLevelGet( ) 
intLockLevelSet{ ) 
intLock( ) 
intRestrict( ) 
intUnlock{ ) 
intVecBaseGet{ ) 
intVecBaseSet( ) 
intVecGet{ ) 
intVecSet() — 
ioDefPathGet{ ) 
ioDefPathSet{ ) 
ioGlobalStdGet{ ) 
ioGlobalStdSet, ) 
ioLib 
ioTaskStdGet{ ) 
toTaskStdSet{ ) 
ioctl ) 
tosDevAdd{ ) 
tosDevDelete({) 
iosDevFind( ) 
iosDevShou ) 
iosDruInstall( ) 
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- - convert dot notation Internet address to long integer...... 


- get local address (host number) from Internet address ... 1-141 
- form Internet address from network and host 


EVURTA YOGI S 95sec Sake Sepsis ceases hake ccaapca ceed as detonate 1-142 
- form Internet address from network and host 

TRUE OTS ici sass scans ses ccesonspusicssucenncscesecedesssauascestauSeessutusccasesi Saasihs 1-142 
- return network number from Intemet address.................. 1-143 
- extract network address in dot notation............scsccssssessseee 1-144 
- convert Internet network number from string to 

GAQTOSS 5S iiecssei Sirs ti asis alcatel cechae ieee Cara caters 1-145 
- convert network dot notation address to ASCTI.............. 1-145 
- convert network dot notation address to ASCII................ 1-146 
- display all active connections for Internet protocol 

SOCKEIS siaasisteemicnecen a suarndiencennactex eld te ea sesaetuceeiuacs 1-244 
- interrupt library assembly language routines..............000 1-147 
- connect C routine to hardware interrupt ......... ee eeeeeeeeee 1-149 
- determine if we are in interrupt context or task 

COTS NE nsssece gases Soca cia tes sae as av ates Sade west esadeae espace 1-152 
- get current interrupt nesting Cepth......... nc sccsessessesseesssees 1-153 
- construct interrupt handler for C routine... esses 1-150 
Set Ierupe LEVEL since istics gical iat ales: 1-147 
- interrupt Subroutine HDrary...........eccsesessssssecsssscesseesesseeseeseeees 1-148 
- get current interrupt lock-out level uuu... cessesessesssesessesseesnes 1-152 
- set current interrupt lock-out level... essessessssssesssesessesees 1-151 
SHOCK OUT TALOTIU DUNS secs cess ceseatsnctitesdicussctacbalustduaaststsacgealsaadeaareess 1-153 
- restrict interrupt context from using routine ...........c. 1-152 
= Cancel effect OF MULOCK sicclsinscscscsnesssasesnctsses see deecees seevensetessateseds 1-154 
- Bet VectOr base AAAIESS..........sssescssssesecsecsesssesseseescsesensssssensseees 1-155 
=Set VECIOr DASS AGCIOSS sosissasncsaisinces scuctescesssanasnsdsstssensaesstetionsiens 1-155 
SOU MV CCLOE sags seats isles as tas cascades cased evadecdetesterataaeattecueacnss 1-156 
eet CEU VeClOr icine i shseeaieioshiaaticierteteiitaicontataice 1-156 
- get current default path .....cescssssssesssssessessesssesssssesceseneseeees 1-167 
= Set Current Gefailt Path ss..ccczcccaccceccsocsessateasteucen ses ctsatecssscartersceene 1-166 
- get fd for global standard in/out /error ...... ess eessssseeeseeseeeee 1-169 
- set fd for global standard in/out /e1T0T.........essesssesessssseeeene 1-169 
17 © tnterace MD TAn ys cssissshcelstettidecs cea hectaesteclectareneeccies 1-158 
- get fd for task standard in/out / Error .........cesssssesssecesseeseeees 1-170 
- set fd for task standard in/Out /TTOL........cssssssssssssstsseeeeeees 1-170 
- perform file-specific COMO] FUNCTION ........cssecsssescssseeesssesseee 1-165 
- add device to [/O System on... cecsssescssssesessesseesnessessnseseeeneeeaees 1-175 
- delete device from I/O SYSteM.........esseecnescesseesnessessecseecsessness 1-175 
- find I/O device in device list... sscsscsssecsecenssesseecsneeenseeees 1-176 
- display list of devices im SYSteM........ssecssssessessessesssesseeseess 1-176 
=install/ Order tea nee ania. 1-173 
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tosDrvoRemove( ) ‘+ remove I/O driver. SS siovaasSusctles asus benseatGiinees neater le 174 
tosDrvShou ) - display list of system Grivers ........sssssssscsssesseeeesen seddisiialantasts 1-174 
iosFdShou{) — - display list of fd mames im SySteM............sssscossescensesneeeconeeen 1-177 
iosFdValue( ) - validate open fd and return driver-specific value.............. 1-177: 
iosInit{ ) ~ imitialize I/O SYSteOM........cscccscssccsesssssssscscscscnecessssersoncnsansoves seveee 1-173 
iosLib - 1/O system .......sscscseesees Besiciesrees sreneeant eshte lai taneeretee ones 1-172 
_ tpstatShow( ) SES Play: UP SARS TACS occ.5sscsscicasnassaseasencssnconsonssonsasisdon anon cvecsaesects 1-244 
isatty( ) - return whether underlying, driver i is tty device ............. wo 1-371 
jump - show jumpering of target and associated board............... 3-4 
kernelInit{ ) - initialize kernel uu... cesssessseees euzuessies cveneeetbdestsectediataudeapatbsttiasts 1-179 
kermelLib = VX9OO KeMmeLIDIaly aiccasse tice tia lava nauanemtaian 1-178 
kernelTimeSlice{ ) - enable round-robin selection .........cesscesssssssesssescescsetersesceserors 1-181 
kernelVersion( ) - Teturn kerrel reviSion String... ..escesssssscosssssssnesssessesesssesseeene 1-180 
kill() - send signal to task... esssscssesesceees Lbpidauades estes satin 1-349 
Id) - load object MOdule intO MEMOTY...........ssseessesessssssecsrsseasseee 1-499 
ledClose{ ) - discard line-editor ID............ccccssscesscssssccesassesessescssasscaescsescarocees 1-185 
ledControl( ) - change line-editor ID parameter ............ssssssessssresseessesseeseees 1-186 
ledLib - line-editing library.......... beseetael augea betas ian hcweait asics detcesatetvetoaas 1-182 
ledOpen( ) - create NeW lime-editOr ID ou... scssscsssssseeeceeseesesecssserssseceseaees 1-184 
ledRead( ) - read line with lime-editing 0.0... scssssssssssecsecessessesessesseensseesecs 1-185 
I() - disassemble and display specified number of 
| "SNS ERUGHIONS :cjecte eis tcc se eas valerie ieeanak 1-31 
listen( ) - enable connections to SOCKet.....sescssssccecseesscesncsececassesesseeees 1-353 
[kAdadr{ ) - list symbols whose values are near given value ................ 1-505 
Tkup ) SAISE LOD al SV EVO IS casted pss caa tence cticecustenccettcaseasttoctetsceda easeetieeiese 1-505 
1) - do long listing of directory CONTENES .......cessssessssssesseesesseeeee 1-501 
Inattach( ) - attach In interface to NEtWOTK .0........cccssscessecsssectecncscsscesenserees 1-132 
loadLib = Object MOdulle loader -cccscssssscsscsenosnsnesseressssucsensasssescovaccursnseansesss 1-187 
loadModuleAt{ ). - load object module into MEMOTY............cssessssssessssserssseesees 1-188 
loadModule( ) - load object module into NO seater siete 1-188 
logFdAdd{ ) SACL LOG MIN 1 aos Setsitacscats sal esace Sea sade eeccad aie wauiectetsatecleaaeie nics 1-196 
logFdDelete{ ) IACI C TOS HINGE 5s Setsccies sca sccccscsaudaonsccatadsns cpnsaicasvicdantastestabeaticceus 1-197 
logFdSet{ ) _ BISOE PTT ALY IO CAN LR eccsesatt ans hauasa sears serscaneneasi ess dacactestaeaslte 1-196 
logInit{ ) - initialize message logging HDrary .............sescssccsecssesssessecsnsees 1-194 
logLib - message logging HDraxy..........--cccrsssecerssessecnsnnessscensescceneeesene 1-192 
logMsg{ ) = Jog formatted error Message ..........cscsscsssccesssssesscscenseesaseeseees 1-194 
logTask{ ) - Message-loggINg SUPPOTt tASK .......sccsrersesseeasscsesssseersseessenes 1-197 
loginDefaultEncrypt{) - default password encryption routine..........eccessccssssessecsesseses 1-205 
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loginEncryptInstall() — - install encryption routime.........--.cserecssserensssesssmeseesseereeseees 1-204 


oo ) - initialize login table .............s.secsccsscecssevecacesceesseceeeesesseeseesenecseeee 1-200 
- user login/password subroutine hibrary ................eee 1-198 
mel ) - display login prompt and validate user entry................... . 1-203 
loginStringSet{ ) ~ Change login String... ...-ssecssssesoceerssoeessesesssesseneeessenssssssseresesees 1204 
loginUserAdd{ ) - add user to login table ..........-s-.seesseesesesessemeceseneereenerssssensenees 1-200 
loginUserDelete{ ) - delete user entry from login table... ...--s-sseecsnsssveessesessveee 1-201 
loginUserShow ) - display user login table... ......sssssssessscenseescseneentesenseeeseesseecs 1-202 
loginUserVerify{ ) - verify user name and password in login table................... 1-202 
logout() — - log out of Vx960 a aenemntne 1-510 
longjmp ) - perform non-local Zoto......-..0vsssse suisssacissanciie, Loa 
IsOld( ) - list contents of RT-11, ftp, ot rsh directory..... sesseeeseee 1-502 
lseek{ ) - set file read/write poiriter 1... nescsseeccsseseesesnsennscnsensees 1-165 
Is). ~ list contents Of GireCtOTy -1-........n..-sncsesceceersssesseceseesassensesseeseeeseee 1-500 
lstAdd{ ) - add node to end Of list... esssssacscseceescosesscseceseressensseseeees 1-209 
lstConcat{ ) - CONCAatenate WO Hists nn. seessecseeneesecseeeseeenesceesesscsesassesees 1-209 
IstCount{ ) - report number Of NOES i Hist -............enssssecsseeesseesecnseesecseoesees 1-210 
IstDelete( ) - delete specified node from pone sep itcs heeled aaa: 1-210 
IstExtract, ) - extract Sublist from list... .-.cesccscsssesensssssnsesececsssesenerseceeeee 1-211 
IstFind{) - find node in list... eepnec sea eesitaea e en LO 
IstFirst{ ) _ find first node in list... eeerer ern ene mmmramn onsvmer (94 
IstFree{ ) - free up list ... paseetetnate te So sstidecetiesietaceseic Ie 
lstGet{ ) | - delete and return first node from ist. Sciatica tees 1-212 
IstInit{ ) ~ initialize list descriptor... .....-.sseccsessssseseecenscnsnoeensensenesees 1-208 
IstInsert{ ) __ = insert node in list after specified NOE... --sssssssssenseanes 1-212 
IstLast{ ) - firnd last node in list... ne. se-secsenseseeevseesenscessenseceeneseeseneseeees 1-213 
IstLib - doubly linked list subroutine library .....0......-.nseeessesssseneeee 1-207 
IstNStey{ ) - find list node nStep nodes _ from a node....... 1-215 
IstNext{ ) - find next node in list ................... Paper eonemnnremeed PA We: 
IstNth( ) = find Nth node mi list.2.66 coche oi anes e cece 1-214 
IstPrevious( ) fir previous NOE i Hist .......-....escsssesssessessesnecesseeeeeeneesseeeeees 1-214 
mRegs{ ) - modify registers... sciatica ee LOS 
makeStatTbl - make table of status values.. be daotalaieas scsuet te siees eee east 3-5 
makeSymTbl - make table of symbols Nace 8 oiiee seein, oO 
makeVersion - create Vx960 VerTSION MOU 2... escecceeeecereceseeesceeaseneeees 7 
malloc ) - allocate block of memory from. system memory 
DAT UMOM ios dos ieee rece election aan 1-225 


mb87030CtriCreate{) __- create control structure for mb87030 SPC .......ccceee 21 
mb87030C tl Init{ ) - initialize control structure for mb87030 SPC ow... 23 


mb87030Lib - Fujitsu mb87030 SCSI Protocol Controller (SPC) Library 2-1 
mbufShour ) - TePOrt Mbuf statistics... esesccsesecsecseeeessoeecenssnesosseeesensenees 1-245 


memAddToPool( ) - add memory to system memory partition....................... 1-224 
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memDevCreate{ ) = CHEALE MEMOTY COVICE ...-.cescesensnserecseccoeenescssecorersscesconeenesensoenseeis 2-6 
memDrv - pseudo MeEMOTY Cevice CVE ........csssssesseccsrsscsssesecssesssnsssseneee 2-5 
memDrv{ ) = UniStall MEMOLY GHV OR cies cesserssoscdsestiasaies scdeasndsodesscesdonscuesdecseanseate 2-6 
memFindMax{ ) - find largest free block in system memory partition .......... 1-227 
mem Lib - the Vx960 MEMOTLY MANABET .......ccescssrscrersescssssessssecesesessesseeees 1-217 
memOptionsSet( ) - set debug options for system memory partition................ 1-224 
memPartAddToPool() - add memory to MeMOry pax>titiON...........cesscerseesersssesseeereees 1-220 
memPartAlloc( ) - allocate block of memory from specified partition............ 1-221 
memPartCreate{ ) + CHEATS MEMOPY PAtEION asasasssascsssaseseatssscessesncdssssasssoasseosaiecinsicers 1-219 
memPartFindMax() _ - find size of largest available free DIOCK..0.w ee sesescsseeeee 1-223 
memPartFree( ) - free block of memory in specified partition... 1-222 
memPartOptionsSet{ ) - set debug options for mMeMOTY PartitiON qu... ees 1-221 
memPartRealloc( } - reallocate block of memory in specified partition.............. 1-222 
memPartShow ) - show partition blocks and statistics... essesssesesssoseseen 1-223 
memShour ) - show system memory partition blocks and statistics....... 1-228 
m() SPINOCIU VTICIIOLY sous sisescsesoscsstes arate acceasens tivation orenaoys 1-493 
mkdir( ) SNAKE GUECOUY: strates agi catenin 1-502 
msgOQCreate( ) - create and initialize Message QUEUE... ceecsssstsscessesesseeeees 1-231 
msgQDelete{ ) = GClELE INESSARC GUC C isc Seseciuslincsaarern ait se cain sain: 1-232 
msgQinfoGet ) - get information about message QUCUE......ssssssseseesseseeees 1-236 
msgQLib = Messave queue DIAL siesisicesscssiesestsoiseceleon asec aiaatenecnersees 1-230 
msgQNumMsgs( ) - get number of messages queued to message queue......... 1-235 
msgQRecetve( ) - Teceive Message FLOM MESSABE QUEUE 1.0... seseccsesecseesseeeeees 1-234 
msgQSend( ) - Send message tO MESSAZE QUEUE ou... eecsseesesseesesseesseeeseeeeees 1-233 
msgQShou ) - show information about message QUueUE .........essseeceseeees 1-238 
netDevCreate( ) - Create remote file deVICE uu... eesssscssseeccessscsesesercesscscesneeceeees 2-10 
netDrv - network remote file [/O driver oo. eessscssecssceecessecceneeneee 2-8 
netDrv{ ) - install network remote file river ...cecsecsessssesssessssseeseeeeee 2-10 
netHelpt ) - print synopsis of network TOULINES ... ee eeeeseseeseceeeeeteseeees 1-483 
netLibInit{ ) - IMitialize MEtWOTK PACKALE 0. essceseseesssecesseseecseeteeceesseeeeaeaeees 1-240 
netLib - network interface lDATy oe esse csaceeesesseescneseeseeneessneeeetes 1-240 
netShow!Init ) = initialize network SHOW TOUMNES ou... ecsestscseneseeseeeseecseceeees 1-245 
netShow - network related information display routines... 1-242 
netTask( ) - network taSk entry POINt ue eesssessseeceeesceccneateeneeeeescneees 1-241 
_ nfsAuthUnixGet{ ) - get NFS UNIX authentication parameters... ceeseeeeseee 1-252 
nfsAuthUnixPrompt{) - modify NFS UNIX authentication parameters.............000 1-251 
nfsAuthUnixSet{ ) - set NFS UNIX authentication parameters 0... essere 1-252 
nfsAuthUnixShou{) — - display NFS UNIX authentication PATAMELETS ....--eeeeeeereee 1-251 
nfsDevShou ) - display mounted NFS Gevice......cccsecsssscesesessesssssessssssaeeesees 2-16 
nfsDrv - Network File System [/O rivet.....escsssessssssssessessssesessssees 2-12 
nfsDrv{ ) SINS tal IN FS Griv ef since cain gucierntetierruticteteeneenivercnneens 2-14 
nfsExportShow ) - display exported file systems of remote hOSt..........cesseeseees 1-250 
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nfsHelp( ) 
nfsIdSet{ ) 


nfsLib 
nfsMountAll ) 
nfsMount{ ) 
nfsUnmount( ) 
ntoh{( ) 

ntohs( ) 


opendir( ) 
open() 


picLib 
pipeDevCreate( ) 
pipeDrv 


ramDevCreate( ) 
ramDrv 


ramDro ) 
rawFsDevInit{ ) 
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- display NFS help menu .............sccsscsessssscccssosnssncssessessessneseneneese 1-249 
- set ID number of NFS UNIX authentication 

PAL AIOE OES 5 sssassiciscsestacsaasecasacsucctssssnchasdecesnsWeesepecucssserssoreneceeceatesns 1-253 
- Network File System HDrary ............cssccscsssssssseseresssrscesesseseeees 1-248 
- mount all file systems exported by specified host............. 2-15 
- mount NFS file system ..............ssssssessssssecssesssessessessensesessescsess 2-15 
- UNMOUNE NFS device .........ccscscsssesococscsssserscsssccarscssscscscaserssnssenes 2-16 
- convert long (32 bit) from network to host byte order..... 1-393 
- convert short (16 bit) from network to host byte 

ONCOL ase stig aso eee le cect catetie rence 1-394 
- Open directory for Searching .........sesecsssssessesseessssssssssssessesscenes 1-36 
ROSEN TN ascii casio eaten dee act asd cdaseteed coe ane ste apaestsliendinsstetanics 1-162 
- Sleep until occurrence Of Sigmial ...........ssssssssssssscssesessessseseesees 1-348 
- return contents Of PCW register .........ssssssssssesssssesssssseseees 1-507 
- Call function periodically .........cscssessscssesesssssssssssssssssasesesseeees 1-485 
- spawn task to call function periodically .........sssssssssessssees 1-485 
- return contents of register pfp (also sp, rip, r3-r15, g0-214, 

| 8) eae sere rere va ener ore ie er npr ORED ne ene rere rr rT rrorre -506 
- JUMP PrOgramM SUPPOTT TOULINES .........ccssessecsssseerersseesenseeeeeees 3-8 
= CLEALE PAPO GOVINO 2 sasiisssp sae Se esc tes alas dav aan niasiaseaeadtnenits 2-21 
ey St Gace CBO eg \1 <4 gee emee cei eoter mere ane amen are rere srenneT ny erste ee 2-18 
~ Initialize Pipe CGTIVET.............cscesseccsscesceccossseacseeenssnsnecsussescessonsacsoes 2-20 
- print formatted string to standard er7OF............ssssssessseeees 1-83 
- print definition of specified error status value...............0000 1-509 
SOPDEITIL VX DOU BO PO sitcscia cs coctcai sce wsaredatestestasshavtien sal ch ctetseneeioauion 1-510 
- print formatted string to standard Out... ssssssescnesssseese 1-81 
- Create pseudo termimal .......esessssssecssesecessessssessssesseesseeesoes 2-23 
- pSeudo-terminal Griver........cessssscseesecsseccesseserseesessesseeseesseeeses 2-22, 
- initialize pseudo-terminal driver... ssesssssssesesesesseseeees 2-23 
- append character to output Stream... sesssssseesesseesee 1-389 
- append character to standard out stream ............csscsssssseees 1-388 
- copy NULL-terminated string to output stream ............... 1-380 
- append word (32-bit integer) to output stream................ 1-381 
- print current default directOTy ou... ssscssssssessscssnssesssesseeseees 1-496 
- create RAM disk Gevice..........ccsscsscssssussorsscssecsnsssucsessesssenssoseees 2-26 
= RAM Gish GEV Gi sssctishessccttntecerctea eset cus ei taceinniitens 2-25 
- prepare RAM disk driver for use (optional)............ssses00 2-26 
- associate block device with raw volume functiona............ 1-258 
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rawFsInit{ ) - prepare to use raw volume Hibrary.............cssssssssssorsenssesesesece 
.awFsLib - raw block device file system HbDrary............cscsssssssssseesnecssees 
rawFsModeChange{) - modify mode of raw device VOLUME............cssssscssssnecssescsess 
rawFsReadyChange() - notify rawFsLib of change in ready status ........... esses 
rawFsVolUnmount()  - disable raw device VOIUME............cssssssssscssssscssecssscncecssecssnsscecs 
remd{ ) - execute shell command on remote machine ...........cssccseees 
readdir( ) - Fead One entry frOM CiKectOTY.........ssccsssssseerereaseresesnesseseseseesesses 
read( ) - read bytes from file OF GEVICE........ccsssssesesssecnssssscesesssssnesserseeses 
realloc( ) - reallocate block Of MEMOTY ........csscsccesessssserscsssesesesessseseeseeseees 
rebootHookAdd( ) - add routine to be called at reboot.......... igpaitecedeneseneoetadis 
rebootLib =TEDOOE SUPPOTE WDTATY sissy safes cass cvcsccsssansscacsdsavescasaotusassennsacsosies 
reboot ) - reset network devices and transfer control to boot 
BROOMS sist Sse a casashcaobsdedii uss cqan nrcotentecentiatis seated nuspiabaasetnasgetiaes 
recu ) - receive ata from SOCKEL..........ccssssssscesscscesssescesersssesacesenssescscerees 
recufrom( ) - Teceive Message fro SOCKEt.........scsssssessesssesenssssssrsssssesasseeses 
recuntsg{ ) | - Teceive Message frOM SOCKEL.......csesessssssssssesssseseesssssseseseesesens 
remCurldGet( ) - get current user name and PasSWOTK ........cscccsssescsseeseessesesees 
remCurldSet( ) - set remote user NaMe ANd PASSWOT........esssscesseesssesseesesseees 
remLib - FeMOte COMMANA HDrAaY.w. i. cessessseessesesesseseseeeescessnssecsseseenes 
remove( ) Bec) (1 Co || ee eo ENE ere noe eee ae NRT eer SO re Ne oe eT 
rename( ) -change name of file i.cesscscseereaninunaanwnisusenonanala 
repeatRun( ) - Call function repeatedly uc ssscsssessesssssesssessessesssssssessssessseees 
repeat{ ) - spawn task to call function repeatedly .......sssscccsssssssesesees 
rewinddir( ) - reset position to Start Of GITECOTY.........cssssssssessscseessssesseeeees 
rewind ) - position stream at DegiNNIN .........cseesccsssesessecesseceesseseceeseceenes 
rlogInit{ ) - initialize remote login facility... sscsssssesseesssssessseseesseese 
rlogLib STEMOte LOGI ND TAY. oiccciestscdeccccsus chats extaxs adesscanasseviesddchssncesabadene 
rlogind{ ) - the Vx960 remote login daeMon......ccsssscssseeseessesseeseeees 
rlogin() + 1OP In tO TEMOlE NOSE waascsctintrceseciasianinasdataeintnain: 
redir( ) SMEMOVE CILECLOLY 52a sec reste taeienasdan seats 
rei) SOTO VC Lie sixshishescetesaceseessaasiettdoeant ates ats eae es 
rgBufGet, ) - get characters from Ting DUffeL..... ees eeseseecsececnesssseceeseeee 
mgBufPut( ) - put bytes into ring buffer sscssesssecsssessessesseesssseeesesseeees 
rngCreate( ) - create empty ring buffer... ssesccsseceeceececsssecoessesseaesevesees 
rngDelete( ) ~ delete ring buffer 20.0.0... csssssssscesccssosesesssscsssessesaescccnscecseeassonsees 
rngFlush{ ) - make ring buffer empty... cescscccsesssessecsssecsessccsesaeecesseneeee 
rngFreeBytes( ) - determine number of free bytes in ring buffer... 
rglsEmpty( ) - test if ring buffer is EMPty.........ececsessesssesssessessessessnssnesssssssssees 
rngisFull( ) - test if ring buffer is full (no more TOOM) ........esesseeneeee eae 
mgLib - Ting buffer subroutine Hbrary .......... es scsesssssseeceseeeseeesaneeees 
rngMoveAhead( ) - advance ring pointer by 11 DyteS oc cssssseecsessseneseeseeens 
mgNBytes( ) - determine number of bytes in ring buffer... ssessssseeees 
mgPutAhead( ) - put byte ahead in ring buffer without moving ring 
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romStart( ) - Zerneric ROM initialization... ssccssseessscseesesenesssceesateceeess 1-11 
routeAdd( ) AAG TOULE siecicisicctecasceeceicnisesas Po ero rere errr oer 1-281 
routeDelete( ) SLE LOLS TO UE cccasesechsscctvasestenshceuseecciat ees caeee eats aapieeeateienessaenss 1-282 
routeLib - network route manipulation library .............ssscssssssssssessseees 1-281. 
routeShou ) - display host and network routing tables............sessscesessseees 1-283 
rpcinit( ) ~ initialize RPC package ..u........scscsseccssssosseseesseosereesssessnesseneesseeess 1-286 
rpcLib = RPC Support NDrary sds si ocetcastiiaii hee caatiaied 1-285 
rpcTaskInit( ) - initialize task’s access to RPC package..........csssssscsscsssseerssees 1-286 
rresuport{ ) - open socket with privileged port bound to it ..... eee 1-266 
rt11FsDateSet{ ) = SOU CUTFENE GAO scsi decdescareststieciae oe cca Reese renee 1-295 
rt11FsDevIinit( ) - initialize RT-11 device descriptor oc esesessceeceeseneeeneenees 1-292 
rt11FsInit( ) - prepare to use RT-11 brary... cs eseseescseseessecsssseseness 1-294 
rt11FsLib - RT-11 media-compatible file system library... cess 1-287 
rt11FsMKkfs( ) - initialize device and create RT-11 file system... 1-294 
rt11FsModeChange({) - modify mode of RT-11 VoOlUME we scssscessesseeseeeeeeneeece 1-296 
rti1FsReadyChange() - notify rt11FsLib of change in ready status 0... eee 1-296 
sbicShow ) - display values of all readable wd33c93 chip registers....... 2-32 
scanf() - read and convert characters from standard in stream...... 1-382 
scsiAutoConfig( ) - configure all devices connected to SCSI controllet............ 1-304 
scsiBlkDevCreate() — - define logical partition on SCSI block device .....sssssssssssse 1-306 
scsiBlkDevInit{ ) - initialize fields in SCSI logical partition 0... eseeseeneee 1-306 
scsiBusReset{( ) - pulse reset signal On SCSI DUS ...... cc cescessssessensessesessneesseeceseee 1-307 
scsiFormatUnit{ ) - issue FORMAT_UNIT command to SCSI device............... 1-308 
scsilnquiry( ) - issue INQUIRY command to SCSI device... 1-308 
scsiloctl( ) - perform device-specific CONETO] FUNCTION 0... ecsseescseeseseeees 1-312 
scsiLib - Small Computer System Interface (SCSI) librarry............... 1-298 
scsiModeSelect{ ) - issue MODE SELECT command to SCSI device.............0. 1-309 
scsiModeSense({ ) - issue MODE SENSE command to SCSI device .............04 1-309 
scsiPhysDevCreate{) - create SCSI physical device Structure... esessssesessssseeneeees 1-303 
scsiPhysDevDelete{) - delete SCSI physical device Structure.......sssesssssesseesees 1-303 
scsiPhysDevIdGet({) —_- return pointer to SCSI physical device SEFUCTUTE vases 1-304 
scsiRdSecs( ) - read sectors from SCSI block device... cessesesssesesseeseseees 1-310 
scsiReadCapacity()  - issue READ CAPACITY command to SCSI device......... 1-310 
scsiReqSense( ) - issue REQUEST SENSE command to device and read 

WS NES scl coast cea tiates aad estat eens ere ete eres ce 1-311 
scsiShow ) - list physical devices attached to SCSI controller............... 1-305 
scsiTestUnitRdy( ) - issue TEST UNIT_READY command to SCSI device..... 1-307 
scsiWrtSecs( ) - write sectors to SCSI Dlock device ou... csseccsesecesesecssseseesees 1-311 
selNodeAdd( ) - add wake-up node to select( ) wake-up list «00... eesssseeeee 1-316 
selNodeDelete( ) - find and delete node on wake-up list ....... ee csessceeseseceneseees 1-317 
selWakeupAll( ) - wake up all tasks on select{ ) wake-up listo... sesso 1-316 
selWakeupListInit{) — - initialize select{ ) wake-up Hist 0... escsesssessscscseeneseenseeee 1-317 
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selWakeupListLen( ) 


semClear{ ) 
_semCreate{ ) 
semDelete( ) 
semFlush( ) 
semGive{ ) 
semInfor } 
semInit( ) 
semLib 
semMCreate( ) 
semMGiveForce( ) 


semMLib 
semOLib 
semtlake{ ) 
send() 
sendmsg ) 
sendtot ) 


shellHistory{ ) 
shellInit{ ) 
shellLib 
shellLock() 
shellOrigStdSet( ) 
shellPromptSet{ ) 
shellScriptAbort( ) 
shell() 
shutdown() 


sighnit{ ) 
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- mutual-exclusion semaphore library 
- version 4.x binary semaphore library 
- take semaphore 
- send data to socket 
- send message to socket 
- send message to socket 
- specify buffer to be used on stream 
- set buffer to be used on stream 
- set symbolic name of this machine 
- set non-local goto 
- set line buffering for either sidout or stderr 
- set socket options 


- display (or set) shell history 


- set shell’s default input/output /error fds 
- change shell prompt 
- signal shell to stop processing script 
- the shell entry point 
- shut down network connection 
- initialize signal facilities 
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- get number of nodes on select( ) wake-up list............000 1-318 
- get type of given SEL_WAKEUP_ NODE 
- wake up task pended in select{ ) 
- initialize select{ ) library 
- UNIX BSD 4.3 select library 
- pend on set of fds 
- create and initialize binary semaphore 
- binary semaphore library 
- create and initialize counting semaphore 
- counting semaphore library 
- take version 4.x semaphore if semaphore is available...... 1-337 
- create and initialize version 4.x binary semaphore............ 1-336 
- delete semaphore 
- unblock every task pended on semaphore 
- give semaphore : 
- get list of task IDs that are blocked on semaphore............ 1-330 
- initialize static binary semaphore 
- general semaphore library 
- create and initialize mutual-exclusion semaphore............ 1-334 
- give mutual-exclusion semaphore without 
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sig Lib - software sieval faciity BDGALY «.siscelesseciceeteee cds eadcntes 1-343 
sigRaise{ ) = SOU SISTA! UO CASK alascissinciss esses cesdatshadict ts jetiapotcassaveacienansocanesests 1-349 
sigblock( ) - add to set of blocked sigmals ...........s.:cssssssssssssssscosseseesesesseees 1-348 
sigsetmask( ) SOE SIP TAAL NAS hese as casines caste sass ccentas sentecsanecapeoseanicscersesteldats 1-347 
-sigstack( ) - install separate signal stack sesgesia sibs tase teens sorssbanieaaveiseacoass 1-347 
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NAME 
abs - absolute value routine 


SYNOPSIS 
abs( ) - absolute value of an integer 


int abs (1) 


NAME 

abs( ) - absolute value of an integer 
SYNOPSIS 

int abs (i) 

int i; /* integer for which to return absolute value */ 

DESCRIPTION 

This routine returns the absolute value of the specified integer. 
RETURNS 

The value i if 1 is positive, or -i if 1 is negative. 
SEE ALSO 

abs 
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NAME 


bLib - buffer manipulation library 


SYNOPSIS | 
memccpy() - copy upto n bytes of second buffer to first or until c is copied 
memchr( ) - return pointer to first occurance of char if in n bytes of buffer 
memcmp( ) - compare first n bytes of two buffers numerically, byte for byte 
memcpy() - copy n bytes of second buffer to the non-overlapping first 
memmove() - copy n bytes of second buffer to the possibly overlapping first 
memset() - set n bytes of buffer to the given value 
bcopy()- copy n bytes from first buffer to second as quickly as possible 
bcopyBytes( ) - copy n bytes from first buffer to second, a byte at a time 
bcopyWords( ) - copy n shorts from first buffer to second, a short at at time 
bcopyLongs( ) - copy n longs from first buffer to second, a long at a time 
bfill( ) - fill buffer with n chars, may optimize to multi-byte stores 
bfillBytes( ) - bfill one byte at a time 
bzero{ ) - fill buffer with n zero bytes, may optimize to multi-byte stores 
bcmp() - same as ANSI memcmp 
binvert( ) - reverse the order of bytes in the buffer 
bswap( ) - swap the contents of two buffers 
swab{ ) - swap n bytes in from first buffer, place in second 


void * memccpy (void *dest, const void *source, int c, int n) 
void * memchr (const void *s, int c, size_t n) 

int mescep (const void *sl, const void *s2, size_t n) 
void * memcpy (void *dest, const void *source, size_t n) 
vold * memmove (void *dest, const void *source, size t n) 
void * memset (void *buf, int c, size_t n) 

woid bcopy (char *source, char *dest, int n) 

vold bcopyBytes (char “source, char *dest, int nbytes) 
void bcopyWords (char *source, char *dest, int nwords) 
void bcopyLongs (char ‘source, char *dest, int nlongs) 
void bfill (char *s, int nbytes, unsigned char v) 

vweid bfillBytes (char *s, int n, unsigned char v) 

void beero (char *s, int n) 

int bemp (char *sl, char *s2, int n) 

void binwert (char *s, int n) 

void bewap (char “source, char “dest, int n) 

void swab (char ‘source, char *dest, int n) 
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DESCRIPTION 
This library contains routines that duplicate the ANSI-compliant versions of 
the UNIX buffer processing package and also supplies several tradition as 
well as Vx960 specific buffer manipulation routines. The functions operate 
on variable lenth arrays of bytes. They do not check for the overflow of any 
resulting strings, nor do they check for null termination as the routines of 
strLib do. 


NOTE 

The non-ANSI routine memccpy(), and the ANSI routines memchr(), 
memcmp(), memcpy(), memmove(), and memset() actually come from 
libraries supplied with your compiler tool set, for example the Intel 
GNU/960 tool set. The documentation for these routines are not included 
as part of Vx960, but they are documented in the GNU/960 documentation 
set in the book “C, A Reference Manual,” by Samuel P. Harbison and Guy L. 
Steele Jr. | 


INCLUDE FILE 
#include “‘strLib.h’ 


SEE ALSO | : 
strLib, ““C, A Reference Manual,’ Harbison and Steele, Prentice Hall 


NAME 


bcmp() - compare one buffer to another 


SYNOPSIS 2 
int bomp (bufl, buf2, nbytes) 
char ‘*bufl; /* pointer to first buffer «/ 
char *buf2; /* pointer to second buffer */ 
int nbytes; /* number of bytes to compare */ 
DESCRIPTION 
This routine compares the first nbytes characters of buf1 to buf2. 


RETURNS 
0 = first nbytes of bufl and buf2 are identical 
-1 = buf! is less than buf2. 
1 = bufl1 is greater than buf2 
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SEE ALSO 
| bLib, GNU memcmp 


NAME 


binvert( ) - invert the order of bytes in.a buffer 


SYNOPSIS 
VOID binvert (buf, nbytes) 
char *buf; /* pointer to buffer to invert */ 
int nbytes; /* number of bytes in buffer */ 


DESCRIPTION : 
This routine inverts an entire buffer, byte by byte. For example, the buffer 
{1,2,3, 4,5} would become {5, 4, 3, 2, 1}. 


RETURNS 
N/A 


SEE ALSO 
bLib, GNU libc doc or source 


NAME 
bswap({ ) - swap buffers 


SYNOPSIS 


VOID bswap (bufl, buf2, nbytes) 
char ‘*bufl; /* pointer to first buffer */ 
char *buf2; /* pointer to second buffer */ 
int nbytes; /* number of bytes to swap */ 


DESCRIPTION 
This routine exchanges the first nbytes of the two specified buffers. 


RETURNS 
N/A 
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NAME 
swab() - swap bytes 
SYNOPSIS 
VOID swab (source, dwstination, nbytes) 
char “source; /* pointer to source buffer */ 
char ‘destination; /* pointer to destination buffer */ 
int nbytes; /* number of bytes to exchange */ 
DESCRIPTION 


This routine gets the specified number of bytes from source, exchanges the 
adjacent even and odd bytes, and puts them in destination. The buffers 
source and destination should not overlap. It is an error for nbytes to be odd. 


RETURNS 
N/A 


SEE ALSO 
bLib 
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NAME 
bzero( ) - zero out a buffer 
SYNOPSIS 
VOID bszero (buffer, nbytes) 
char *buffer; /* buffer to be zeroed «/ 
int nbytes; /* number of bytes in buffer */ 
DESCRIPTION 
This routine fills the first nbytes characters of the specified buffer with 0. 
RETURNS 
N/A 
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SEE ALSO 
bLib, memset 
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NAME 
bcopy( ) - copy one buffer to another 
SYNOPSIS 
VOID boopy (source, destination, nbytes) 
char *source; /* pointer to source buffer */ 
char ‘destination; /* pointer to destination buffer */ 
int nbytes; /* number of bytes to copy «/ 
DESCRIPTION 


This routine copies the first nbytes characters from source to destination. 
Overlapping buffers are handled correctly. Copying is done in the most effi- 
cient way possible, which may include long-word, or even multiple-long- 
word moves on some architectures. In general, the copy will be significantly 
faster if both buffers are long-word aligned. (For copying that is restricted 
to byte, word, or long-word moves, see the manual entries for 
bcopyBytes( ), bcopyWords( ), and bcopyLongs( ).) 


RETURNS 
N/A 


SEE ALSO 
bLib, bcopyBytes( ), bcopyWords( ), bcopyLongs( ), memcpy( ) 


NAME 
bcopyBytes( ) - copy one buffer to another one byte at a time 


SYNOPSIS 
VOID boopyBytes (source, destination, nbytes) 
char ‘source; /* pointer to source buffer «/ 
char ‘destination; /* pointer to destination buffer */ 
int nbytes; /« number of bytes to copy «/ 
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DESCRIPTION 
This routine copies the first nbytes characters from source to destination one 
byte at a time. This may be desirable if a buffer can only be accessed with 
byte instructions, as in certain byte-wide memory-mapped peripherals. 


RETURNS 
N/A 


SEE ALSO 
bLib, bcopy( ) 


NAME 
bcopyWords( ) - copy one buffer to another one word at a time 
SYNOPSIS | 
VOID bcopyWords (source, destination, mrords) 
char *source; /* pointer to source buffer «/ 
char ‘destination; /* pointer to destination buffer */ 
int nwords; /* number of words to copy «/ 
DESCRIPTION 


This routine copies the first nwords words from source to destination one 
word at a time. This may be desirable if a buffer can only be accessed with 
word instructions, as in certain word-wide memory-mapped peripherals. 
The source and destination must be word-aligned. 


RETURNS 
N/A 


SEE ALSO 
bLib, bcopy( ) 


NAME 
bcopyLongs( ) - copy one buffer to another one long word at a time 
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SYNOPSIS 
VOID bcopyLongs (source, destination, nlongs) 
char ‘source; /* pointer to source buffer «/ 
char ‘destination; /* pointer to destination buffer */ 
int - nilongs; /* number of longs to copy «/ 
DESCRIPTION 


This routine copies the first nlongs characters from source to destination one 
_long word at a time. This may be desirable if a buffer can only be accessed 

with long instructions, as in certain long-word-wide memory-mapped peri- 

pherals. The source and destination must be long-aligned. | 


RETURNS 
N/A 


SEE ALSO 
bLib, bcopy() 


NAME 
bfill( ) - fill buffer with a specified character 
SYNOPSIS 
VOID bfill (buf, nbytes, ch) 
char *buf; /* pointer to buffer */ 
int nbytes; /* number of bytes to fill «/ 
unsigned char ch; /* char with which to fill buffer */ 
DESCRIPTION 


This routine fills the first nbytes characters of a buffer with the character ch. 
Filling is done in the most efficient way possible, which may be long-word, 
or even multiple-long-word stores on some architectures. (For filling that is 
restricted to byte stores, see the manual entry for bftllBytes( ).) 


RETURNS 
N/A 


SEE ALSO 
bLib, bfillBytes( ), memset 
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NAME 
bfillBytes( ) - fill buffer with a specified character one byte at a time 
SYNOPSIS 
VOID bfillsytes (buf, nbytes, ch) | | 
: char «buf 3 /* pointer to buffer «/ 
int nbytes; /* number of bytes to fill «/ 
unsigned char ch; /* char with which to fill buffer */ 
DESCRIPTION | 


This routine fills the first nbytes characters of the specified buffer with the 
character ch one byte at a time. This may be desirable if a buffer can only be 
accessed with byte instructions, as in certain byte-wide memory-mapped 
peripherals. 


RETURNS 
N/A 


SEE ALSO 
bLib, bfill( ) 
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NAME 


bootConfig - system configuration module for boot ROMs 


SYNOPSIS 


NO CALLABLE ROUTINES 


DESCRIPTION 


1-10 


This is the Intel-supplied configuration module for the Vx960 boot ROM. It 
is a stripped down version of usrConfig.c, having no Vx960 shell or debug- 
ging facilities. Its primary function is to load an object module over the net- 
work with either rsh or ftp protocols. Additionally, a simple set of single 
letter commands is provided for displaying and modifying memory con- 
tents. Use this module as a starting point for placing applications in ROM. 
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NAME 


bootInit - ROM initialization module 


SYNOPSIS 3 
romStart( ) - generic ROM initialization 


VOID rom@tart (startType) 


DESCRIPTION 
This module provides a generic boot ROM facility. The target-specific 
romInit.s module does the minimal preliminary board initialization and then 
jumps to the C routine romStart{ ). This routine, still executing out of ROM, 
copies the first stage of the startup code to a RAM address and jumps to it. 
The next stage clears memory and then uncompresses the remainder of 
ROM into the final Vx960 ROM image in RAM. | 


A modified version of the Public Domain compress program is used to 
uncompress the Vx960 boot ROM executable linked with it. Compressing 
object code typically achieves a 40% compression factor, permitting much 
larger systems to be burned into ROM. The only expense is the added few 
seconds delay while the first two stages complete. 


SEE ALSO 
compress(), romInit( ) 


AUTHOR | 
The original compress program was written by: Spencer W. Thomas, Jim 
McKie, Steve Davies, Ken Turkowski, James A. Woods, Joe Orost. 


NAME 


romStart( ) - generic ROM initialization 


SYNOPSIS 
VOID rométart (startType) 
int startType; 


DESCRIPTION 
This is the first C code executed after reset. 


This routine is called by the assembly start-up code in romInit{). It clears 
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memory, copies ROM to RAM, and possibly invokes the uncompressor. It 
then jumps to the entry point of the uncompressed object code. 


RETURNS 
N/A 


SEE ALSO — 
bootInit 


1-12 Intel Rev: 29 Aug 91 


Reed 


 “tprares(1) bootLib: ° : 


NAME 
bootLib - boot ROM subroutine library 


SYNOPSIS 
bootStringToS truct{ ) - interpret the boot parameters from the boot line 
bootStructToString( ) - construct a boot line 
bootParamsShow, ) - display boot line parameters 
bootParamsPrompt ) - prompt for boot line parameters 
bootNetmaskExtract( ) - extract netmask field from Internet address 
bootBpAnchorExtract{ ) - extract backplane address from device field 


char “bootStringToStruct (bootString, psootParams) 
STATUS bootStructTostring (paranGtring, pBootParams ) 
VOID bootParamsShow (paraxString) 

VOID bootParamsPrompt (string) 

STATUS bootNetmaskExtract (string, pNetmask) 


STATUS bootBpAnchorExtract (string, pAnchorAdrs) 


DESCRIPTION 
This library contains routines for manipulating a boot line. Routines are 
provided to interpret, construct, print, and prompt for a boot line. 


When Vx960 is first booted, certain parameters can be specified such as net- 
work addresses, boot device, host, and start-up file. This information is 
encoded into a single ASCII string known as the boot line. The boot line is 
placed at a known address (specified in config.h) by the boot ROMs so that 
the system being booted can discover the parameters that were used to boot 
the system. The boot line is the only means of communication from the boot 
ROMs to the booted system. 


The boot line is of the form: 


bootdev (0, procnum) hostname: filename e«# b=# h=# g=# u=userid pw-passwd f=¢ 
tn=targetname s=startupscript o~other 


where: 

bootdev - the boot device (e.g., “ei” for Intel 82596 LAN coprocessor, 
“bp” for backplane). For the backplane, this field can have 
an optional anchor address specification of the form 
““bp=adrs"’ (see bootBpAnchorExtract, )). 

procnum - the processor number on the backplane (0..n). 
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the name of the boot host. 
the file to be booted. | 


the Internet address of the Ethernet interface. This field can 
have an_ optional subnet mask of the form 
inet_adrs:subnet_mask (see bootNetmaskExtract{ )). 


the Internet address of the backplane interface. This field 
can have an optional subnet mask as “’e’”’. 


the Internet address of the boot host. 


the Internet address of the gateway to the boot host. Leave 
this parameter blank if the host is on same network. 


a valid user name on the boot host. 


the password for user on the host. This parameter is usu- 
ally left blank. If specified, then ftp is used for file 
transfers. 


the system-dependent configuration flags. This parameter 
contains an or of option bits defined in sysLib.h. 


the name of the system being booted 
the name of a file to be executed as a start-up script. 
“other’ string for use by the application. 


The Internet addresses are specified in “dot” notation (e.g., 90.0.0.2). The 
order of assigned values is arbitrary. 


bootLib.h 


EXAMPLE 
ei(0,0) host: /usr/vw/maz7122/config/vx¥orks e=90.0.0.2 b=91.0.0.2 


h=100.0.0.4 


g=30.0.0.3 u=bob pwerealtime f=2 tn=target 


sshost:/usr/bob/startup o~any string 
SEE ALSO 


bootConfig 
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NAME 
bootStringToStruct{ ) - interpret the boot parameters from the boot line 


SYNOPSIS 
char *bootStringToStruct (bootString, pSootFarams) 
char *bootString; /* boot line to be parsed */ 
BOOT PARAKS “pBoot Params} /* structure to be filled */ 


DESCRIPTION 
This routine parses the ASCII string and returns the values into the pro- 
vided parameters. 


See the manual entry for bootLib for a description of the format of the boot 
line. 


RETURNS | 
A pointer to the last character successfully parsed plus one (points to EOS if 
OK). The entire boot line is parsed. 


SEE ALSO 
bootLib 


NAME 
bootStructToString( ) - construct a boot line 


SYNOPSIS 
STATUS bhoctStructToString (perae=sString, pSoot Params) 
char *paramString; /* where to return the encoded boot line «/ 
BOOT _PARAMG *pSocotParams; 
DESCRIPTION : 
This routine encodes a boot line using the specified boot parameters. 


See the manual entry for bootLib for a description of the format of the boot 
line. 


RETURNS 
OK 
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SEE ALSO _ 
bootLib 


NAME 
bootParamsShow ) - display boot line parameters 


SYNOPSIS 
VOID bootParamsShow (parazString) 


char ‘*paramGtring; /* boot parameter string */ 


DESCRIPTION 
This routine displays the boot Patemictere: in the specified boot string one 
parameter per line. 


SEE ALSO 
bootLib 


NAME 
bootParamsPrompt( ) - prompt for boot line parameters 


SYNOPSIS 
VOID boot ParamsPrompt (string) 
char ‘string; /* default boot line */ 


DESCRIPTION 
This routine prompts the user for each of the boot parameters. For each 
parameter, the current value is displayed and a new value is prompted for. 
Typing a RETURN leaves the parameter unchanged. Typing a period (.) 
clears the parameter. 


The parameter string is used for the initial values. A new boot line will be 
produced or changed as the user specified. That line will be copied over 
string. If there are no initial values, string should be empty on entry. It is the 
caller's responsibility to assure that string is long enough to hold the full 
boot line. 
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NAME 
bootNetmaskExtract{ ) - extract netmask field from Internet address 


SYNOPSIS 
STATUS bootNetmaskExtract (string, piletmask) 
char ‘string; /* string containing adrs field */ 
int pNetmask; /* pointer where to return netmask */ 


DESCRIPTION 
This routine extracts the optional subnet mask field from an Internet address 
field. Subnet masks can be specified for an Internet interface by appending 
to the Internet address a colon and the net mask in hexadecimal. For exam- 
ple, the “inet on ethernet’ field of the boot parameters could be specified as: 


inet on ethernet: 90.1.0.1: ££££0000 


In this case, the network portion of the address (normally just 90) is 
extended by the subnet mask (to 90.1). This routine extracts the optional 
trailing subnet mask by replacing the colon in the specified string with an 
EOS and then scanning the remainder as a hex number. This number, the 
net mask, is returned via the pNetmask pointer. 


RETURNS 
A 1 if the subnet mask in string is specified correctly, 0 if the subnet mask in 
string is not specified, or -1 if an invalid subnet mask is specified in string. 


SEE ALSO 
bootLib 
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bootBpAnchorExtract{ ) - extract backplane address from device field 


SYNOPSIS | 


STATUS bootBpAnchorExtract (string, pAnchorAdrs) 
char ‘string; /* string containing adrs field */ 
char ‘**pAnchorAdrs; /* pointer where to return anchor address */ 


DESCRIPTION 


RETURNS 


This routine extracts the optional backplane anchor address field from a 
boot device field. The anchor can be specified for the backplane driver by 
appending to the device name (i.e. ‘“‘bp’”’) an equals sign (=) and the address 
in hexadecimal. For example, the ‘“boot device” field of the boot parameters 
could be specified as: 


boot device: bp=-800000 


In this case, the backplane anchor address would be at address 0x800000, 
instead of the defauit specified in config.h. 


This routine picks off the optional trailing anchor address by replacing the 
equals sign (=) in the specified string with an EOS and then scanning the 
remainder as a hex number. This number, the anchor address, is returned 
via the pAnchorAdrs pointer. 


A 1 if the anchor address in string is specified correctly, 0 if the anchor 
address in string is not specified, or -1 if an invalid anchor address is speci- 
fied in string. 


SEE ALSO 
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NAME 
cALib - C-language support routines 


SYNOPSIS 
setjmp() - set non-local goto 
longjmp( ) - perform non-local goto 


int setjmp (env) 
VOID longjmp (env, val) 


DESCRIPTION 
This library contains C-language support routines. It includes the “‘non- 
local goto” routines setjmp() and longjmp(), and other routines and data 
necessary to satisfy the compilers or libraries of particular host systems. 


INCLUDE FILE 
setjmp.h 


NAME 
setjmp() - set non-local goto 


SYNOPSIS 
int setjmp (env) 
jmp buf env; /* where to save stack environment */ 


DESCRIPTION | 
This routine saves the current task context and program counter in env for 
later use by longjmp(). It returns 0 when called. However, when program 
execution returns to the point at which setjmp() was called and the task 
context is restored by longjmp( ), setjmp( ) will then return the value val, as 
specified in longjmp( ). 


RETURNS 
0 or val if return is via longjmp( ). 


SEE ALSO 
cALib, longjmp( ) 
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NAME 
longjmp() - perform non-local goto 
SYNOPSIS 


VOID longjmp (env, val) 
jup_buf env; /* where stack environment was saved * 
int val; /* value for setjmp to return « 


DESCRIPTION 
This routine restores the previously saved setjmp() context and jumps to 


where setjmp() was called. The routine setjmp( ) will then return the value 
val. 


NOTE | 
This routine does not return anything. Instead, it causes setjmp() to return 


val. If val is 0, then 1 is returned. 


RETURNS 
N/A 


SEE ALSO 
cALib, setjmp() 
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NAME 
ctypeLib - character classification and conversion macros 


DESCRIPTION 
This UNIX-compatible library consists of macros that classify or convert 
ASCII-coded characters by table lookup. The macros are defined in ctype.h. 


The following macros take a character parameter and return non-zero for 


TRUE or zero for FALSE. 

isalpha(c) - cis a letter. 

isupper(c) - Cis an upper case letter. 

islower(c) - cis a lower case letter. 

isdigit(c) - cis a digit. 

isxdigit(c) - cis a hexadecimal digit. 

isspace(c) - cis a space, tab, carriage return, newline, or formfeed. 

ispunct(c) -c is a punctuation character (neither control nor 
alphanumeric). 

isalnum(c)  - cisan alphanumeric character. 

isprint(c) - c is a printable character, code 040 (space) through 0176 
(tilde). 

isgraph(c) - c is a visible graphics character, code 041 (exclamation 
mark) through 0176 (tilde). 

iscntrl(c) - c is a delete character (0177) or ordinary control character 
(less than 040). 

igascii(c) - cis an ASCII character, code less than 0200. 


These macros perform simple conversions on single characters. 


toupper(c) - converts c to its upper case equivalent. 

tolower(c) - converts c to its lower case equivalent. 

toascii(c) - forces c to be ASCII (strips highest eighth bit of character). 
INCLUDE FILE 

ctype-h 


Rev: 29 Aug 91 Intel 1-21 


NAME 
dbgLib - debugging facilities 


SYNOPSIS 
dbgHelp( ) - display debugging help menu 
dbgInit( ) - initialize debug package 
b( ) - set or display breakpoints 
db( ) - set a data breakpoint 
bd() - delete breakpoint 
bdall( ) - delete all breakpoints 
c()- continue from breakpoint 
cret( ) - continue until return from current subroutine 
s{) - single-step 
so( ) - single-step, but step over subroutine 
I( ) - disassemble and display a specified number of instructions 
tt{ ) - print a stack trace of a task 


VOID dbgHlelp () 

STATUS dbgInit (breakpointTrapNum) 

STATUS b (addr, taskNameOrId, count, quiet) 
STATUS db (addr, access, taskNameOrId, count, quiet) 
STATUS bd (addr, taskNameOrId) 

STATUS bdall (taskiameOrId) 

STATUS c (taskNameOrId, addr) 

STATUS cret (taskNameOrId) 

STATUS s (taskNameOrId, addr) 

STATUS so (taskNameOrId) 

VOID 1 (pInstr, count) 

STATUS tt (taskMameOrId) 


DESCRIPTION 
This module provides Vx960’ primary interactive debugging routines, which 
provide the following facilities: 


- task breakpoints 

- task single-stepping 
In addition, dbgLib provides the facilities needed to provide enhanced use 
of other Vx960 modules, including: 


- symbolic disassembly (via dsmLib), 
- symbolic task stack tracing (via treLib), 
- enhanced shell-abort and exception handling (via tyLib and excLib). 
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The facilities of excLib are used by dbgLib to support breakpoints, single- 
stepping, and additional exception-handling functions. 


INITIALIZATION | 
The debugging facilities provided by this module are optional. In the stan- 
dard Vx960 development configuration as distributed, the debugging pack- 
age is included in a Vx960 system by defining INCLUDE_DEBUG in 
configAll.h. This will enable the call to dbgInit{) in the task usrRoot( ) in 
usrConfig. The dbgInit({) routine initializes dbgLib and must be called 
before any other routines in the module are called. 


BREAKPOINTS 
Use the routine b( ) to set breakpoints. Breakpoints can be set to be hit by a 
specific task or by all tasks. Multiple breakpoints for different tasks can be 
set at the same address. Clear breakpoints with bd( ) and bdall( ). 


When a task hits a breakpoint, the task is suspended and a message is 
displayed on the console. At this point, the task can be examined, traced, 
deleted, its variables changed, etc. If you examine the task status at this 
point (using i( ) routine), you will see that it is suspended. The instruction at 

the breakpoint address has not yet been executed. | 


To continue executing the task, use the c() routine. At this point, the 
instruction that had contained the breakpoint is executed, and the task will 
then continue. The breakpoint remains in until it is explicitly removed. 


UNBREAKABLE TASKS 
An “unbreakable” task ignores all breakpoints. Tasks can be spawned 
unbreakable by specifying the task option VX_UNBREAKABLE. Tasks can 
subsequently be set unbreakable or _ breakable resetting 
VX_UNBREAKABLE using taskOptionsSet(). Several Vx960 tasks are 
spawned unbreakable, such as the shell, the exception support task, 
excTask( ), and several network related tasks. 


DISASSEMBLER AND STACK TRACER | 
The 1() routine provides a symbolic disassembler, using the low-level 
disassembly routines in dsmLib. The tt ) routine provides a symbolic stack 
tracer, using the low-level stack trace routines in trcLib. 


SHELL ABORT AND EXCEPTION HANDUNG 
This package includes enhanced support for the shell in a debugging 
environment. The terminal “abort” function, which restarts the shell, is 
invoked with the abort key on a terminal for which the OPT_ABORT option 
has been set. By default, the abort key is “C. See the manual entries for 
tyAbortSet{ ) and tyAbortFuncSet, ). 
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DEFAULT TASK | : 
Many routines in this package take a task ID as an argument. If this argu- 
ment is missing or zero, the last task ID referenced is used. The routine 
taskIdDefault() is used to set and get the last referenced task ID, as do 
many Vx960 routines in other modules. 


CAVEATS soe 
Currently, some internals of vxWorks should not have breakpoints placed in 
them. Most notable are semGive() and semTake() which are used to 
manage crucial non-preemptable resources. One may work around this res- 
triction by placing a breakpoint on the call to these routines. 


ARCHITECTURE 
The Vx960 native debugger has been restructured to be more portable across 
cpu architectures. Three files make up the debugger; dbgLib.c, dbgarch Lib.c, 
and dbgALib.s. dbgLib.c contains the architecture independent functions, 
dbgarchLib.c contains the architecture dependent support functions, and 
dbgALib.s contains the assembly language stub for handling debugging 
exceptions. 


SEE ALSO 
excLib, dsmLib, tyLib, tyAbortSet, tyAbortFuncSet 


NAME 
dbgHelp( ) - display debugging help menu 
SYNOPSIS | 
VOID dbgtelp () 
DESCRIPTION 
This routine displays a summary of dbgLib utilities with a short description 
of each: | 
dbgkelp | Print this list 
dbgInit Install debug facilities 
b Display breakpoints 
b addr[,task[,count}} set breakpoint 
bd addr[ ,task] Delete breakpoint 
bdall [task] Delete all breakpoints 
c {task{, addr] } Continue from breakpoint 
cret [task] Continue to subroutine return 
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db addr[access[ ,task[,count)})) Set data breakpoint 


s [task[, addr) } Single step 
20 [task] Single step/step over subroutine 
1 {adr[ ,nInst] J List disassembled memory 
tt [task] Do stack trace on task 
SEE ALSO | 
dbgLib, “Debugging” 


NAME 
dbgInit{ ) - initialize debug package - 


SYNOPSIS 
STATUS dbgInit (breakpointTrapNun) 
int breakpointTrapNum; /* trap number for breakpoints */ 


DESCRIPTION 
This routine installs the debug package. This involves: 


- setting the interrupt vectors of the breakpoint 
and trace hardware interrupts to the appropriate 
debug interrupt handlers, 


- adding the debug task switch routine to the kernel 
context switch call out, 


- setting the terminal “abort” function to restart 
the shell, 


- setting the exception handling extension to 
trace and restart the shell if the exception 
occurred in the shell task. 


WHEN TO CALL | 
It is usually desirable to install the debugging facilities as early as possible in 
system initialization, if the debugging facilities are to be included at all. It 
should not, however, be called until the pipe driver, the ty driver used for 
logging, the exception handler library (excLib (1)), and message logging 
library (logLib (1)) have been initialized. 


RETURNS 
OK, or ERROR if unable to install task switch routine 
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NAME 
b( ) - set or display breakpoints 
SYNOPSIS 
STATUS b (addr, taskNameOrId, count, quiet) 
INSTR *addr; /* where to set breakpoint, or +f 
/* 0 = display all breakpoints «/ 
int taskWameOrId; /* task for which to set breakboint, */ 
/* 0 = set all tasks */ 
int count; /* mumber of passes before hit */ 
BOOL quiet; /* TRUE = don’t print debugging info, */ 
/* FALSE = print debugging info «/ 
DESCRIPTION 


This routine is used to set or examine breakpoints. To see the list of currently 
active breakpoints, call b{ ) without arguments: 


-> b 


The list shows the address, task and passcount of each breakpoint. The rou- 
tines so( ) and cret{ ) insert temporary breakpoints and are so marked. 


To set a new breakpoint with b( ), call it with an address, which can be speci- 
fied numerically or symbolically with an optional offset. The other argu- 
ments are optional: 


-~> b addr [,task [,passcount) [, quiet] ] 


If the task argument is zero or missing, the breakpoint will apply to all 
breakable tasks. If passcount is zero or missing, the breakpoint will occur 
every time it is hit. If passcount is specified, the break will not occur until the 
passcount+I1st time an eligible task hits the breakpoint (i.e., the breakpoint is 
ignored the first passcount times it is hit. 


If quiet is specified, debugging information destined for the console will be 
supressed when the breakpoint is hit. This option is included for use by 
external source code debuggers that handle the breakpoint user interface 
themselves. 


Individual tasks can be ‘‘unbreakable’ in which case breakpoints that 
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otherwise would apply to a task are ignored. Tasks can be spawned 
unbreakable by specifying the task option VX_UNBREAKABLE. Tasks can 
also be set unbreakable or breakable by setting or resetting 
VX_UNBREAKABLE with the routine taskOptionsSet{ ). 


RETURNS 
OK, or ERROR if addr is odd or non-existent in memory, or if the breakpoint 
table is full. 


SEE ALSO 
dbgLib, bd, taskOptionsSet, Programmer's Guide: Debugging 
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NAME 
db( ) - set a data breakpoint 
SYNOPSIS 
STATUS db (addr, access, taskNameOrId, count, quiet) 
INSTR *addr; /* where to set breakpoint, or «/ 
/* 0 = display all breakpoints «/ 
UINT32 access} /* access type * / 
/* 00 - store only «/ 
/* 01 - data only (load or store) «/ 
/* 10 —- data or instruction fetch «/ 
/* 11 - any access «/ 
int taskMameOrId; /* task for which to set breakboint, « / 
/* 0 = set all tasks */ 
int count; /* number of passes before hit «/ 
BOOL quiet; /* TRUE = don’t print debugging info, */ 
/* FALSE = print debugging info */ 
DESCRIPTION | 


This routine is used to set a data breakpoint (not to be confused with bd{ )). 
If the architecture allows it, this function will add the breakpoint to the list 
of breakpoints, and set the hardware data breakpoint register(s). see D{ ) 
above. 


RETURNS 
OK or ERROR. 


SEE ALSO 
dbgLib 
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NAME 
bd( ) - delete breakpoint 
SYNOPSIS 
STATUS bd (addr, taskNameOrId) 
INSTR *addr; /* address of breakpoint to delete «/ 
int taskNemeOrId; /* task for which to delete breakpoint, */ 
/«* 0 = delete for all tasks «/ 
DESCRIPTION 


This routine is used to delete a specific breakpoint. To execute, type: 
-> bd addr [, task] 


If task is missing or zero, the breakpoint will be removed for all tasks. If the 
breakpoint applies to all tasks, removing it for only a single task will be inef- 
fective. It must be removed for all tasks, and then set for just those tasks 
desired. Temporary breakpoints inserted by so( ) or cret{ ) may be deleted. 


RETURNS 
OK, or ERROR if there is no breakpoint at the specified address. 


SEE ALSO 
Programmer's Guide: Debugging dbgLib, b 


NAME 
bdall( ) - delete all breakpoints 


SYNOPSIS 
STATUS bdall (taskiameOrId) | 
int taskNameOrId; /* task for which to delete breakpoints, */ 
/* 0 = delete for all tasks «/ 


DESCRIPTION 
This routine is used to remove all breakpoints. To execute, type: 


-> bdall [task] 


If a task is specified, all breakpoints that apply to that task are removed. If 
task is omitted, all breakpoints for all tasks are removed. Temporary 
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breakpoints inserted by so{ ) or cret( ) are not deleted; use bd{ ) instead. 


RETURNS 
OK (always) 


SEE ALSO 
dbgLib, bd, Programmer's Guide: Debugging 
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NAME 
c( ) - continue from breakpoint 


SYNOPSIS 
STATUS c (taskNameOrId, addr) 
int taskNameOrId; /* task that should proceed from breakpoint « / 
int addr; /* address to continue at; 0 = next instruction */ 


DESCRIPTION 
This routine is used to continue execution of a task that has stopped at a 
breakpoint. To execute, type: 


-> c [task [,addr] ] 
If task is omitted or zero, the last task referenced is assumed. If addr is non- 
zero, the program counter is changed to addr, and the task is continued. 


RETURNS 
OK, or ERROR if the specified task does not exist. 


SEE ALSO 
dbgLib, tr, Programmer’s Guide: Debugging 


NAME 
cret() - continue until return from current subroutine 


SYNOPSIS 
STATUS cret (taskameOrId) 
int taskKameOrId; /* task to continue, 0 = default */ 
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DESCRIPTION 
This routine places a breakpoint at the return address of the current subrou- 
tine of a specified task, then continues execution of that task. 


To execute, type: 
—> cret [task] 


If task is omitted or zero, the last task referenced is assumed. 


When the breakpoint is hit, information about the task will be displayed in 
the same forma! as in single-stepping. The breakpoint is automatically 
removed when hit, or if the task hits another breakpoint first. 


RETURNS : 
OK, or ERROR if there is no such task, or if the breakpoint table is full. 


SEE ALSO 
dbgLib, so, Programmer's Guide: Debugging 


NAME 
s() - single-step 
SYNOPSIS | 
STATUS s (taskiKemeOriId, addr) 
int taskMNameOrId; /* task to step; 0 = use default . «/ 
int addr; /* address to step to; 0 = next: instruction */ 
DESCRIPTION | 
This routine is used to single-step a task-that 4s:stopped at:a-breakpoint. To 
execute, type: tae 3 


—> s (task [,addr] ] 


If task is missing or zero, the last task referenced is assumed. If addr is non- 
zero then the program counter is changed to addr and the task is stepped. 


SEE ALSO 
dbgLib, Programmer's Guide: Debugging 
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NAME 
so( ) - single-step, but step over subroutine 
SYNOPSIS 
STATUS so (tackNameOrI¢) 
int taskNameOrId; /* task to stap; 0 = use default */ 
DESCRIPTION 


This routine is used to singie-step a task that is stopped at a breakpoint; 
however, if the next instruction is a JSR or BSR, it breaks at the instruction 
following the subroutine call instead. 


-> go [tesk]) 


If task is missing or zero, the last task referenced is assumed. 


SEE ALSO 
dbgLib, Programmer's Guide: Debugging 


NAME 
I( ) - disassemble and display a specified number of instructions >. ~ 
SYNOPSIS 
VOID 1 (pInstr, count) 
INSTR *pInstr; /* Address of first instruction to disassemble, -*/= An shee w.. 


wie 


/* 4£ 0, continue from the last instruction“ '1ce/fo70 The bss 
| /* disassembled on the last call to 1. Se: or 
int count; /* Waumber of instruction to disassemble,  «s* - #/ 8682 7 


/* if 0, use the same as the last call tol. 8 */ = 7 - 
DESCRIPTION 


This routine dissasembles a specified number of instructions and displays 
them on standard output. If the address of an instruction is entered in the 
system symbol table, the symbol will be printed as a label for that instruc- 


tion. Also, addresses in the op-code field of instructions will be printed 
symbolically. 


To execute, enter: 


-> 1 [addr [,count]] 
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If addr is omitted, disassembly continues from the previous address. If count 
is omitted, the last specified count is used (initially 10). As with all values 
entered via the shell, the address may be typed symbolically. 


SEE ALSO | 
dbgLib, Programmer's Guide: Debugging dsmLib 
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NAME. 
tt( ) - print a stack trace of a task 


SYNOPSIS 
STATUS tt (taskNameOrId) 
int taskNameOrId; /* task whose stack is to be traced */ 


DESCRIPTION 
This routine prints a list of the nested routine calls that the specified task j is 
in. Each routine call and its parameters is displayed. 


If the task argument is missing or zero, the last task referenced is assumed. 
tt( ) can only trace the stack of a task other than itself. For instance, when 
tt( ) is called from the shell, it cannot trace the shell’s stack. 


This higher-level symbolic stack trace is built on top of the low-level rou- 
tines provided by the routines in trcLib(1). | 


EXAMPLE 
-> tt “logTask" 
3ab92 vxTaskEntry +10:  logTask () 


eese  logTask +12-: read () 

d460 read +10:: iosRead () 

e234 iosRead +9c : pipeRead () 

23978 pipeRead +24 : semTake (3f8b78, 0, 0, 0, 0, 0) 


value = 0 = 0x0 


This indicates that the logTask{ ) is currently in semTake() (with one param- 
eter) and was called by pipeRead, which was called by iosRead, and so on. 


CAVEAT 
In order to do the trace, some assumptions are made. In general, the trace 
will work for all C and assembly language routines, However, routines writ- 
ten in other languages, strange entries into routines, or tasks with corrupted 
stacks, can make the trace very confused. Because the i960 microprocessor 
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passes parameters in global registers, and optimized C code will not neces- 
sarily move any of the parameters to the stack (or other knowable location), 
only the parameters for the last function call will be given. These paramters 
are the values in the first n global registers. Where n is the number given to 
the function trcArgCountSet. The defualt is 5. These parameters are only 
gauranteed if the task hit a breakpoint (or single-step) at the beginning of 
the function. This is because the register in which the parameter was passed 
may have been altered inside of the function. Also, all parameters are 
assumed to be 32-bit quantities, so structures passed as parameters will be 
displayed as some number of long integers. 


RETURNS 
OK, or ERROR if task does not exist. 


SEE ALSO 
dbgLib, Programmer's Guide: Debugging trcLib, UNIX cc manual entry 
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NAME 
dirLib - POSIX directory handling library 


SYNOPSIS 
opendir( ) - open a directory for searching 
readdir( ) - read one entry from a directory 
rewinddir( ) - reset position to the start of a directory 
closedir( ) - close a directory 
fstat() - get file status information 
stat( ) - get file status information using a pathname 


DIR *opendir (dirName) 
struct dirent *readdir (pDir) 
VOID rewinddir (pDir) 

STATUS closedir (pDir) 
STATUS fatat (fd, pStat) 
STATUS stat (name, pStat) 


DESCRIPTION 
This library provides POSIX-defined routines for opening, reading, and clos- 
ing directories on a file system. It also provides routines to obtain more 
detailed information on a file or directory. 


SEARCHING DIRECTORIES 
The basic directory operation determine the names of files and subdirec- 
tories in a directory. The opendir(), readdir( ), rewinddir(), and closedir( ) 
routines provide this ability. | 


A directory is opened for reading using opendir(), specifying the name of 
the directory to be opened. The opendir() call returns a pointer to a direc- 
tory descriptor, which identifies a directory stream. The stream, is initially © 
positioned at the first entry in the directory. f 


Once a directory stream is opened, the readdir( ) function is used to obtain 
individual entries from it. Each call to readdir( ) returns one directory entry, 
in sequence from the start of the directory. The readdir( ) function returns a 
pointer to a dirent structure, which contains the name of the file (or subdirec- 
tory) in the d_name field. } 


The rewinddir{ ) routine resets the directory stream to the start of the direc- 
tory. After rewinddir() has been called, the next readdir() will cause the 
current directory state to be read in, just as if a new opendir( ) had occurred. 
The first entry in the directory will be returned by the first readdir( ). 
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The directory stream is closed by calling closedir( ). 


GETTING FILE INFORMATION 
The directory stream operations described above provide a mechanism to 
determine the names of the entries in a directory, but they do not provide 
any other information about those entries. More detailed information is pro- 
vided by stat( ) and fstat( ). 


The stat() and fstat() routines are essentially the same, except for how the 
file is specified. The stat() routine takes the name of the file as an input 
parameter, while fstat() takes a file descriptor number as returned by 
open() or creat( ). 


Both routines place the information from a directory entry in a staf structure, 
whose address is passed as an input parameter. This structure is defined in 
the include file stat.h. The fields in the structure include the file size, modifi- 
cation date/time, whether it is a directory or regular file, and various other 
values. 


The st_mode field contains the file type, and several macro functions are pro- 
vided to test the type easily. These macros operate on the st_mode field and 
evaluate to TRUE or FALSE SSPeneine, on whether the file is a specific type. 
The macro names are: 


S ISREG - test if regular file 

S_ISDIR - test if directory 

SISCHR _ - test if character special file 
S_ISBLK - test if block special file 
S_ISFIFO | - test if fifo special file 


Oniy the regular file and directory types are used for Vx960 local file sys- 
tems. However, the other file types may appear when getting file status 
from a remote file system (using NFS). 


As an example, the S_ISDIR macro tests whether a particular entry describes 
a directory. It is used as follows: 


char «filename; 
struct stat fileStat; 
atat (filename, &fileStat) ; 


if (S_ISDIR (fileStat.st_mode)) 

printf (“ts is a directory.\n", filename) ; 
else 

printf (“%s is not a directory.\n", filename); 
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See the Is( ) routine in usrLib for an illustration of how to combine the direc- 
tory stream operations with the sfaf() routine. 


INCLUDE FILES 
dirent.h, stat.h 


NAME 
opendir() - open a directory for searching 


SYNOPSIS 
DIR *opendir (dirName) 
char ‘*dirName; /* name of directory to open */ 


DESCRIPTION 
This routine opens the directory named by dirName and allocates a directory 
descriptor (DIR) for it. A pointer to the DIR structure is returned. The 
return of a NULL pointer indicates an error. 


After the directory is opened using opendir(), the readdir( ) routine is used 
to extract individual directory entries. Finally, closedir( ) is used to close the 
directory. 


RETURNS 
A pointer to a directory descriptor, or NULL if there is an error. 


SEE ALSO | 
dirLib, closedir( ), readdir(), rewinddir( ), Is() 


NAME 
readdir( ) - read one entry from a directory 


SYNOPSIS 
struct dirent *readdir (pDir) 
DIR ‘*pDir; /* pointer to directory descriptor */ 
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DESCRIPTION | 
This routine obtains directory entry data for the next file from an open direc- 
tory. The pDir parameter is the pointer to a directory descriptor (DIR) which 
was returned by a previous opendir( ). 


This routine returns a pointer to a dirent structure which contains the name 
of the next file. Empty directory entries and MS-DOS volume label entries 
are not reported. The name of the file (or subdirectory) described by the 
directory entry is returned in the d_name field of the dirent structure. The 
name is a single null-terminated string. 


The returned dirent pointer will be NULL if at the end of the directory or if 
an error occurred. Because there are two conditions which might cause a 
NULL to be returned, you must use the task’s error number (errno) to deter- 
mine if there was an actual error. You should set errno to OK before calling 
readdir. If a NULL pointer is returned, check the new value of errno. If errno 
is still OK, the end of the directory was reached; if not, errno contains the 
error code for an actual error which took place. 


RETURNS 
A pointer to a dirent structure, or NULL if there is an end-of-directory 
marker or error. 


SEE ALSO 
dirLib, opendir( ), closedir( ), rewinddir( ), Is() 


NAME 
rewinddir( ) - reset position to the start: of a directory 


SYNOPSIS 
VOID rewinddir (pDir) * woe | 
DIR *pDir; /* pointer to directory descriptor */ 


DESCRIPTION 
This routine resets the position pointer in a directory descriptor (DIR). The 
pDir parameter is the directory descriptor pointer that was returned by 
opendir( ). 


As a result, the next readdir() will cause the current directory data to be 

_ read in again, as if an opendir() had just been performed. Any changes in 
the directory that have occurred since the initial opendir will now be visible. 
The first entry in the directory will be returned by the next readdir( ).. 
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RETURNS 
N/A 


SEE ALSO 
dirLib, opendir( ), readdir( ), closedir( ) 


- 
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NAME 
closedir() - close a directory 


SYNOPSIS 
STATUS closedir (pDir) 
DIR ‘*pDir; /* pointer to directory descriptor */ 


DESCRIPTION 
This routine closes a directory which was previously opened using. 
opendir(). The pDir parameter is the directory descriptor pointer that was 
returned by opendir{ ). 


RETURNS 
OK, or ERROR. 


SEE ALSO 
dirLib, opendir( ), readdir( ), rewinddir() 


NAME 
fstat() - get file status information 
SYNOPSIS 
STATUS fstat (fd, pStat) 
int fd; /* file descriptor for file to check */ 
struct stat ‘*pStat; /* pointer to stat structure */ 
DESCRIPTION 


This routine obtains various characteristics of a file (or directory). The file 
must have been previously opened using open() or creat(). The fd parame- 
ter is the file descriptor returned by open() or creat{ ). 


The pStat parameter is a pointer to a sfat structure (defined in stat.h). This 
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structure must have already been allocated before this routine is called. 


Upon return, the fields in the stat structure are updated to reflect the charac- 
teristics of the file. 


RETURNS 
OK, or ERROR. 


SEE ALSO 
dirLib, stat(), Is() 


NAME 
stat() - get file status information using a pathname 


SYNOPSIS 
STATUS stat (name, pStat) 
char t*name; /* name of file to check */ 
struct stat “pStat; /* pointer to stat structure */ 


DESCRIPTION 
This routine obtains various characteristics of a file (or directory). This rou- 
tine is equivalent to fstat(), except that the name of the file is specified, 
rather than an open file descriptor. 


The pStat parameter is a pointer to a stat structure (defined in stat.h). This 
structure must have already been allocated before this routine is called. 


Upon return, the fields in the stat structure are updated to reflect the charac- 
teristics of the file. 


RETURNS 
OK, or ERROR. 


SEE ALSO 
dirLib, fstat( ), Is() 
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NAME 


dosFsLib - MS-DOS media-compatible file system library 


SYNOPSIS 
dosFsConfigInit{ ) - initialize dosFs volume configuration structure 
dosFsDateSet{ ) - set the current date 
dosFsDateTimelInstall( ) - install a user-supplied date/time function 
dosFsDevInit( ) - associate a block device with dosFs file system functions _ 
dosFsInit{ ) - prepare to use the dosFs library 
dosFsMkfs( ) - initialize a device and create a dosFs file system 
dosFsModeChange( ) - modify mode of dosFs volume 
dosFsReadyChange( ) - notify dosFsLib of a change in ready status 
dosFsTimeSet{ ) - set the current time 
dosFsVolUnmount( ) - unmount a dosFs volume 


STATUS dosFsConfigInit (pConfig, mediaByte, secPerClust, nResrvd, nFats, ... 
STATUS dosFsDateSet (year, month, day) 

VOID dosFsDateTimeInstall (pDateTimeFunc) 

DOG VOL DESC *dosFsDevinit (deviame, pBlkDev, pConfig) 

STATUS dosFsInit (maxFiles) 

DOS VOL_DESC “dosFskkfs (vollame, pBlkDev) 

VOID dosFsModeChange (vdptr, newlode) 

VOID doseFsReadyChange (vdptr) | 

STATUS dosFsTixeSet (hour, minute, second) 

STATUS dosFsVolUnmount (vdptr) - 


DESCRIPTION 
This library provides services for file oriented: device drivers to use the MS- 
DOS file standard. This module takes care:ofsalk:the: cede eee 
maintenance, and file system details eee nee WANTECH aero: veer tt or 


USING THIS LIBRARY 
The various functions provided by the Vx960; dosFs: ae eg may be 


tion, and file system operation. 


The dosFsInit( ) function is the principal initialization function; it need only 
be called once, regardless of how many dosFs devices will be used. In addi- 
tion, the dosFsDateTimelInstall( ) function (if used) will typically be called 
only once, prior to performing any actual file operations, to install a user- 
supplied routine which provides the current date and time. 


Other dosFs functions are used for device initialization. For each dosFs 
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device, either dosFsDevInit( ) or dosFsMkfs() must be called to install the 
device and define its configuration. The dosFsConfigInit( )} function is pro- 
vided to easily initialize the data structure used during device initialization; 
however, its use is optional. 


Lastly, several functions are provided to inform the file system of changes in 
the system environment. The dosFsDateSet{) and dosFsTimeSet{) func- 
tions are used to set the current date and time; these are normally used only 
if no user routine has been installed via dosFsDateTimelnstall(). The 
dosFsModeChange( ) call may be used to modify the readability or writabil- 
ity of a particular device. The dosFsReadyChange() function is used to 
inform the file system that a disk may have been swapped, and that the next 
disk operation should first remount the disk. Finally, the 
dosFsVolUnmount{ ) function informs the file system that a particular dev- 
ice should be synchronized and unmounted, generally i in preparation for a 
disk change. 


More detailed information on all of these functions is discussed in the fol- 
lowing sections. 


INITTAUUNG DOSFSLB 
Before any other routines in dosFsLib can be used, the routine dosFsInit( ) 
must be called to initialize this library. This call specifies the maximum 
number of dosFs files that can be. open simultaneously. Attempts to open 
more dosFs files than the specified maximum will result in errors from 


open( ) and creat{ ). 
To enable this initialization, define INCLUDE_DOSFS in configAIl-h)._ 
dosFsInit( ) will then be called from the root task, usrRoot(:),-in ‘usrConfig-c. sO 


DEFINING A DOSFS DEVICE 
To use this library for a particular device, the device descriptor ‘structaré=: 
used by the device driver must contain, as the very first item, a block ‘device } 3:3: ' 
description structure (BLK_DEV). This must be initialized epson rae initia! 
dosFsDevInit({). In the BLK_DEV structure, the driver includes::the *-> © 
addresses of five routines which it must supply: one that reads one:or-thare:-= "!:2 
sectors, one that writes one or more sectors, one that performs I/@:control::.:* +. 
on the device (using ioctl( )), one that checks the status of the devicé,-atid ~‘-:: 
one that resets the device. These routines are described below: The: «-: . 
BLK_DEV structure also contains fields which describe the physical confi- 
guration of the device. See Programmer's Guide: I/O System for more informa- 
tion on defining block devices. 


The dosFsDevInit({ ) routine associates a device with the dosFsLib functions. 
It expects three parameters: 


(1) A pointer to a name string, to be used to identify the device. This will 
be part of the pathname for I/O operations which operate on the 
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device. This name will appear in the I/O system device table, which 
may be displayed using the iosDevShow( ) routine. 


(2) A pointer to the BLK_DEV structure which describes the device and 
contains the addresses of the five required functions. The fields in this 
structure must have been initialized before the call to dosFsDevInit, ). 


(3) A pointer to a volume configuration structure (DOS_VOL_CONFIG). 
This structure contains configuration data for the volume which are 
specific to the dosFs file system. (See “Changes in Volume Configura- 
tion’, below, for more information.) The fields in this structure must 
have been initialized before the call to dosFsDevinit{). The 
DOS_VOL_CONFIG structure may be initialized by using the 
dosFsConfigInit( ) routine. 


As an example: 


dosFsDevinit (volName, pBlkDev, pVolConfig) ; 
char ‘*volKame; /* name to be used for volume  */ 
BLX DEV ‘*pBlkDev; /* pointer to device descriptor */ 
DOG VOL_COMFIG *pVolConfig; /* pointer to vol config data */ 


After the dosFsDevInit{ ) call has been made, when dosFsLib receives a 
request from the I/O system, it calls the device driver routines (whose 
addresses were passed in the BLK_DEV structure) to access the device. 


An alternative to using the dosFsDevInit{ ) routine is the dosFsMkfs({ ) func- 
tion. The dosFsMkfs( ) routine always initializes a new dosFs file system on 
the disk; thus it is unsuitable for disks containing data that should be | 
preserved. Default configuration parameters are supplied by dosFsMkfs( ) 
since no DOS_VOL_ CONFIG structure is used. 


MULTIPLE LOGICAL DEVICES 


The sector number passed to the driver's sector read and write routines is an 
absolute number, starting from sector 0 at the beginning of the device. If 
desired, the driver may add an offset from the beginning of the physical 
device before the start ofithe logical device. This can be done by keeping an 
offset parameter in the driver device structure, and adding the offset to the 
sector number passed by the file system's read and write routines. 


ACCESSING THE RAW DISK 


As a special case in open() and creat() calls, the dosFs file system recog- 
nizes a null filename as indicating access to the entire “raw’ disk rather than 
an individual file on the disk. (To open a device in raw mode, specify only 
the device name — no filename — during the open() or creat{ ) call.) 


Raw mode is the only means of accessing a disk that has no file system. For 
example, when one wants to initialize a new file system on the disk, first the 
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raw disk is opened, and the returned file descriptor is used for an ioctl( ) call 
with FIODISKINIT. Opening the disk in raw mode is also a common opera- 
tion when doing other foctl( ) functions which do not involve a particular 
file (e.g., FIONFREE, FIOLABELGET). 


To read the root directory of a disk on which no file names are known, 
specify the device name when calling opendir( ). Subsequent readdir{ ) calls 
will return the names of files and subdirectories in the root directory. __ 


Data written to the disk in raw mode uses the same area on the disk as nor- 
mal dosFs files and sub-directories. Raw I/O does not use the disk sectors 
used for the boot sector, root directory, or FAT table. For raw disk I/O using 
the entire disk, see the manual entry for rawLib. 


DEVICE AND PATH NAMES 
On true MS-DOS machines, disk device names are typically of the form 
“Az, with a single letter designator followed by a colon. Such names may 
be used with the Vx960 dosFs file system. However, it is possible (and reg 
able) to use longer, more mnemonic device names, such as “DOSI1:’” 
“/floppy0/". The name is epecinied during the dosFsDevInit( ) or 
dosFsMkfs( ) call. 


The pathnames used to specify dosFs files and directories may use either 
forward slashes ("/’’) or backslashes (‘\’’) as separators. These may be 
freely mixed. The choice of forward slashes or backslashes has absolutely 
no effect on the directory data written to the disk. (Note, however, that for- 
ward slashes are not allowed within Vx960 dosFs filenames, although they 
are normally legal for pure MS-DOS implementations.) 


When using the Vx960 shell to make calls specifying dosFs pathnames, you 
must allow for the C-style interpretation which is performed. In cases 
where the file name is enclosed in:quote marks, any backslashes must be 
“escaped” by a second, preceding backslash. For example: 


-> copy ("DOG1:\\subdir\\filel", “file2") 
However, shell commands which use pathnames without enclosing quotes 
do not require the second backslash. For example: 

-> copy < DOG1: \subdir\filel 
Forward slashes do not present these inconsistencies, and may therefore be 
preferable for use within the shell. 


The leading slash of a dosFs pathname following the device name is 
optional. For example, both ‘““DOS1 aware new’ and “DOS1:/new file.new’ 
refer to the same file. 
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READING DIRECTORY ENTRIES 
Directories on Vx960 dosFs volumes may be searched using the opendir( ), 
readdir( ), rewinddir( ), and closedir( ) routines. These calls allow the names 
of files and sub-directories to be determined. 


To obtain more detailed information about a specific file, use the fstat() or 
stat() function. Along with standard file information, the structure used by 
these routines also returns the file attribute byte from a dosFs directory 
entry. 


For more information, see the manual entry for dirLib. 


FILE DATE AND TIME 
Directory entries on dosFs volumes contain a time and date for each file or 
directory. This time is set when the file is created, and it is updated upon 
the close of a file if it has been modified. Directory time and date fields are 
set only when the directory is created, not when it is modified. 


The dosFs file system library maintains the date and time in an internal 
structure. While there is currently no mechanism for automatically advanc- 
ing the date or time, two different methods for setting the date and time are 
provided. 


The first method involves using two routines, dosFsDateSet{) and 
dosFsTimeSet{ ), which are provided to set the current date and time. 


Examples of setting the date and time would be: 


doseFsDateSet (1990, 12, 25); /* set date to Dec-25-1990 */ 
dosFsTimeSet (14, 30, 22); /* set time to 14:30:22 «/ 


The second method requires a user-provided hook routine. If a time and: ~ 
date hook routine is installed using dosFsDateTimeInstgll( ), the routinei:-"-. 
will be called whenever dosFsLib requires the current date. This’ faailityzisi «ict-. 
provided to take advantage of hardware en clocks which: maybe cic: 's vy. 
read to obtain the current time. 


The date/time hook routine should be defined as follows: 
VOID dateTimeliook (pDateTine) 
DOG DATE TD& *pDateTine; /* per to dosFs date/time struct */ 


On entry to the hook routine, the DOS_DATE_TIME structure will contain 
the iast time and date which was set in dosFsLib. The structure should then 
be filled by the hook routine with the correct values for the current time and 
date. Unchanged fields in the structure will retain their previous values. 


The MS-DOS specification only provides for 2-second granularity for file 
time stamps. If the number of seconds in the time specified during 
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dosFsTimeSet{ ) or the date/time hook routine is odd, it will be rounded 
down to the next even number. 


The date and time used by dosFsLib is initially Jan-01-1980, 00:00:00. 


FILE ATTRIBUTES 
Directory entries on dosFs volumes contain an attribute byte consisting of 
bit-flags which specify various characteristics of the entry. The attributes 
which are identified are: read-only file, hidden file, system file, volume 
label, directory, and archive. The Vx960 symbols for these attribute bit-flags 
are: 


DOS ATTR_RDONLY 
DOS ATTR_HIDDEN 
DOS_ATTR_SYSTEM 
DOS ATTR_VOL_LABEL 
DOS ATTR_ DIRECTORY 
DOS ATTR_ARCHIVE 


All the flags in the attribute byte, except the directory and volume label 
flags, may be set or cleared using the ioctl() FIOATTRIBSET function. This 
function is called aiter opening the specific file whose attributes are to be 
changed. The attribute byte value specified in the FIOATTRIBSET call is 
copied directly. To preserve existing flag settings, the current attributes 
should first be determined via the fstat() function, and the appropriate 
flag(s) changed using bitwise AND or OR operations. For se sa to make 
a file read-only, while leaving other attributes intact: 


struct stat fileStat; 


fd = open ("file", READ, 0); /* open file a7; 
fstat (fd, &filestat); /* get file status «/ 


joctl (fd, FIOATTRIBSET, (fileStat.st attrib | DOS _ATTR RDOSLY)); 
/* get read-only flag */ 
Close (fd); /* close file «/ 


CONTIGUOUS FILE SUPPORT 
The Vx960 dosFs file system provides efficient handling of contiguous files, 
meaning files which are made up of a consecutive series of disk sectors. 
This support includes both the ability to allocate contiguous space to a file 
(or directory) and optimized access to such a file when it is used. 


To allocate a contiguous area to a file, the file is first created in the normal 
fashion (using open() or creat()). The file descriptor returned during the 
creation of the file is then used to make an the ioctl() call, specifying the © 
FIOCONTIG function. The other parameter to the FIOCONTIG function is 
the size of the requested contiguous area in bytes. The FAT table is searched 
for a suitable section of the disk, and if found, it is assigned to the file. (If 
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there is no contiguous area on the volume large enough to satisfy the 
request, an S_dosFsLib_ NO CONTIG SPACE error is returned.) The file 
may then be closed or used for further I/O operations. For example, the fol- 
lowing will create a file and allocate 0x10000 contiguous bytes on disk to it: 


fd = creat (“file", UPDATE, 0); /* epen file «/ 
status = ioctl (fd, FIOCONTIG, 0x10000); /* get contiguous area = */ 
if (status != OK) 

Ses /* do error handling «/ 
close (fd); /* close file «/ 


It is important that the file descriptor used for the ioctl({) call be the only 
descriptor open to the file. Furthermore, since a file may be assigned a dif- 
ferent area of the disk than was originally allocated, the ioct] (FIOCONTIG) 
operation should take place before any data is written to the file. 


After the contiguous space has been allocated to a file, the file’s size (kept in 
its directory entry) is unchanged. The size value is increased only as space is 
actually used by writing to the file. 


_ Directories may also be allocated a contiguous disk area. A file descriptor to 


the directory is used to call ioctl (FIOCONTIG), just as for a regular file. A 
directory should be empty (except for the “.” and “..”” entries) before it has 
contiguous space allocated to it. The root directory allocation may not be 
changed. 


When any file is opened, it is checked for contiguity. If a file is recognized as 
contiguous, more efficient techniques for locating specific sections of the file 
are used, rather than following cluster chains in the FAT table as must be 
done for fragmented files. This enhanced handling of contiguous files takes 
place regardless of whether the space. Was actually allocated using 
FIOCONTIG. Pie gee 


CHANGING, UNMOUNTING; AND, SYNCHRONIZING:DISKS - 


Copies of directory entries-and the File Allocation Table (FAT) for each 
volume are kept in memory. This greatly speeds up access to files, but it 
requires that dosFsLib be notified when disks are changed (i.e. floppies are 
swapped). Two different notification mechanisms are provided. 


Unmounting Volumes 


The first, and preferred, method of announcing a disk change is for 


dosFsVolUnmount{ ) to be called prior to removal of the disk. This call 
flushes all modified data structures to disk if possible (see description of 
disk synchronization, below) and also marks any open file descriptors as 
obsolete. During the next I/O operation, the disk is remounted. The ioctl() 
call may also be used to initiate dosFsVolUnmount(), by specifying the 
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FIOUNMOUNT function code. (Any open file descriptor to the device may 
be used in the ioctl( ) call.) 


There may be open files or directories on a dosFs volume when it is 
unmounted. If this is the case, those file descriptors will be marked as 
obsolete. Any attempts to use them for further I/O operations will return 
an“’S dosFsLib FD OBSOLETE” error. To free such file descriptors, use the 
close( ) call, as usual. This will successfully free the descriptor, but will still 
return “’S_dosFsLib_FD_OBSOLETE”. File descriptors acquired when open- 
ing the entire volume (raw mode) will not be marked as obsolete during 
dosFsVolUnmount( ) and may still be used. 


Interrupt handlers must not call dosFsVolUnmount( ) directly, because it is 
possible for the dosFsVolUnmount{ ) call to block while the device becomes 
available. The interrupt handler may instead give a semaphore which 
readies a task to unmount the volume. (Note that dosFsReadyChange( ) 
may be called directly from interrupt handlers.) 


When dosFsVolUnmount{ ) is called, it attempts to write buffered data out to 
the disk. It is therefore inappropriate for situations where the disk change 
notification does not occur until anew disk has been inserted. (The old buf- 
fered data would be written to the new disk.) In these circumstances, 
dosFsReadyChange( ) should be used. 


If dosFsVolUnmount( ) is called after the disk is physically removed (i.e., 
there is no disk in the drive), the data-flushing portion of its operation will 
fail. However, the file descriptors will still be marked as obsolete and the 
disk will be marked as requiring remounting. An error will not be returned 
by dosFsVolUnmount{ ) in:this.situation:. To:avoid lost data in such a situa- 
tion, the disk should be explicitly synchronized before it is removed. 


Announcing Disk Changes: -with:Ready-Change 


The second method of informing; dosFsLib:.that-a disk ean is ie place 
is via the “ready-change’’ mechanism:*:A change in the disk’s ready status is 
interpreted by dosFsLib to indicate that the disk should be remounted dur- 
ing the next I/O operation: 


There are three ways: to announce a_ ready-change. First, the 
dosFsReadyChange( ) routine may be called directly. Second, the ioctl( ) call 
may be used, with the FIODISKCHANGE function code. Finally, the device 
driver may set the “bd_readyChanged” field in the BLK_DEV structure to 
TRUE. This has the same effect as notifying dosFsLib directly. 


The ready-change mechanism does not provide the ability to flush data 
structures to the disk. It merely marks the volume as needing remounting. 
As a result, buffered data (data written to files, directory entries, or FAT 
table changes) may be lost. This may be avoided by synchronizing the disk 
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before asserting ready-change. (The combination of synchronizing and 
asserting ready-change provides all the functionality of dosFsVolUnmount{ ) 
except for marking file descriptors as obsolete.) 


Since it does not attempt to flush data or do other operations which could 
delay, ready-change may be used in interrupt handlers. 


Disks with No Change Notlification 


If it is not possible for dosFsVolUnmount{ ) or dosFsReadyChange() to be 
called each time the disk is changed, the device must be specially identified 
when it is initialized with the file system. One of the parameters of the 
dosFsDevInit( ) call is the address of aDOS_VOL_CONFIG structure, which 
specifies various configuration parameters. The boolean 
“dosvc_changeNoWarn’ field must be set to TRUE if the driver and/or 
application is unable to issue an dosFsVolUnmount{ ) call or assert a ready- 
change when a disk is changed. 


This configuration option results in a significant performance disadvantage, 
because the disk configuration data must be regularly read in from the phy- 
sical disk, in case the disk has been changed. In addition, setting 
“dosvc_changeNoWarn” to TRUE also enables auto-sync mode (see below). 


Note that all that is required for disk change notification is that either the 
dosFsVolUnmount() call or the dosFsReadyChange() call be issued each 
time the disk is changed. It is not necessary that it be called from the device 
driver or an interrupt handler. For example, if your application provided a 
user interface through which an operator could enter a command which 
would result in an dosFsVolUnmount{ ) call before removing the disk, that 
would be sufficient, and “‘dosvc_changeNoWarn’ should be defined as 
FALSE. It is important, however, that such a procedure be followed very 
strictly. 


Synchronizing Volumes 


A disk should be “synchronized” before is is unmounted. To synchronize a 
disk means to write out all buffered data (files, directories, and the FAT 
table) that have been modified, so that the disk is “up-to-date.” It may or 
may not be necessary to explicitly synchronize a disk, depending on when 
(or if) the dosFsVolUnmount{ ) call is issued. 


When dosFsVolUnmount{ ) is called, an attempt will be made to synchronize 
the device before unmounting. If the disk is still present and writable at the 
time dosFsVolUnmount{ ) is called, the synchronization will take place; there 
is no need to independently synchronize the disk. 


However, if the dosFsVolUnmount{ ) call is made after a disk has been 
removed, it is obviously too late to synchronize. (In this situation, 
dosFsVolUnmount{ ) discards the buffered data.) Therefore, a separate 
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ioctl() call specifying the FIOSYNC function should be made before the 
disk is removed. (This could be done in response to an operator command.) 


Auto-Sync Mode 


The dosFs file system provides a modified mode of behavior called “‘auto- 
sync’. This mode is enabled by setting a boolean field (‘“dosvc_autoSync’’) 
in the DOS_VOL_CONFIG structure to TRUE when calling dosFsDevInit( ). 
When this option is enabled, modified directory and FAT table data is writ- 
ten to the physical device as soon as these structures are altered. (Normally, 
such changes may not be written out until the involved file is closed.) This 
results in a performance penalty, but it provides the highest level of data 
security, since it minimizes the amount of time when directory and FAT data 
on the disk are not up-to-date. 


Auto-sync mode is automatically enabled if the volume does not have disk 
change notification (ie. “dosvc_changeNoWarn” is TRUE during 
dosFsDeviInit()). It may also be desirable for applications where data 
integrity in case of a system crash is a larger concern than simple disk I/O 
performance. 


CHANGES IN VOLUME CONFIGURATION 

Various disk configuration parameters are specified when the dosFs device 
is first initialized using dosFsDevInit(). This data is kept in the volume 
descriptor (DOS_VOL_DESC) for the device. However, it is possible for a 
disk with different parameters than those defined to be placed in a drive 
after the device has already been initialized. For such a disk to be usable, the 
configuration data in the volume descriptor must be modified when a new 
disk is present. | 


When a disk is mounted the boot sector information is read from the disk. 
This data is used to update the configuration data in the volume descriptor. 
Note that this will happen the first time the disk is accessed after the volume 
has been unmounted (using dosFsVolUnmount{ )). 


This automatic re-initialization of the configuration data has two important 
implications: 

First, since the values in the volume descriptor will be reset when a new 
volume is mounted, it is possible to omit the dosFs configuration data (by 
specifying a NULL pointer instead of the address of a DOS_VOL_CONFIG 
structure during dosFsDevInit{ )). The first use of the volume must be with 
a properly formatted and initialized disk. (Attempting to initialize a disk, 
using FIODISKINIT, before a valid disk had been mounted would be fruit- 
less.) 


Second, the volume descriptor data is used when initializing a disk (with 
FIODISKINIT). The FIODISKINIT function will initialize a disk with the 
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configuration of the most recently mounted disk, regardless of the original 
specification during dosFsDevInit{ ). Therefore, it is recommended that you 
use FIODISKINIT immediately after dosFsDevInit{ ), before any disk has 
been mounted. (The device should be opened in raw mode, the 
FIODISKINIT function is then performed, and the device is then closed.) 


IOCTL FUNCTIONS 


The Vx960 DOS file system supports the following ioctl() functions. The 
functions listed are defined in the header ioLib.h. Unless stated otherwise, 
the fd used for these functions may be any fd which is opened to a file or 
directory on the volume, or to the volume itself. 


FIODISKFORMAT 
| - Formats the entire disk with appropriate hardware track 
and sector marks. No file system is initialized on the disk 
by this request. Note that this is a driver-provided func- 
tion: 
fd = open ("DEV1:", WRITE); 
status = foctl (fd, FIODISKFORMAT); 


FIODISKINIT - Initializes a DOS file system on the disk volume. This rou- 
tine does not format the disk; formatting must be done by 
the driver. The fd should be obtained by opening the 
entire volume in raw mode: 

fd = open ("DEV1:", WRITE) ; 
status = ioctl (fd, FIODISKINIT) ; 


FIODISKCHANGE | 

- Announces a media change. It performs the same func- 
tion as dosFsReadyChange(. ). vs function may be called 
from interrupt level: | 


status = ioctl (fd, FIODISKCHANGE) } 


FIOUNMOUNT 
- Unmounts a disk volume. It performs the same function 
as dosFsVolUnmount{ ). This function must not be called 
from interrupt level: 


status = ioctl (fd, FIOUNMOUNT) ; 


FIOGETNAME- Gets the file name of the fd and copies it to the buffer 
nameBuf. 
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status = loctl (fd, FIOGETMAME, t&nameBuf ); 


FIORENAME - Renames the file to the string newname: 
status = ioctl (fd, FIORENAME, “newname"); 


Only files (not directories) may be renamed. 
FIOSEEK - Sets the current byte offset in the file to the position speci- 
fied by newOffset: 
status = ioctl (fd, FIOGEEK, newOffset) ; 


FIOWHERE __ - Returns the current byte position in the file. This is the 
byte offset of the next byte to be read or written. It takes 
no additional argument: 


position = ioctl (fd, FIOWHERE); 


FIOFLUSH - Flushes the file output buffer. It guarantees that any out- 
put that has been requested is actually written to the dev- 
ice. If the specified fd was obtained by opening the entire 
volume (raw mode), this function will flush all buffered 
file buffers, directories, and the FAT table to the physical 
device: 


status = ioctl (fd, FIOFLUSEH) ; 


FIOSYNC - Performs the same function as FIOFLUSH. 
FIONREAD __ - Copies to unreadCount the number of unread bytes in the 
file: a 


status = ioctl (fd, FIOCHREAD, -cunreadCount) ; 


FIONFREE _ - Copies to freeCount the amount of free space, in bytes, on 
the volume: | 


status = ioctl (fd, FIOMFREE, &freeCount); 
FIOMKDIR ~~ - Creates a new directory with the name specified as dir- 
Name. 
status = foctl (fd, FIOMKDIR, "dirweme"); 
FIORMDIR ~~ ~- Removes the directory whose name is specified as dir- 


Name: 
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status = ioctl (fd, FIORMDIR, "dirtName"); 


FIOLABELGET- Gets the volume label (located in root directory) and 
copies the string to labelBuffer: 


status = foctl (fd, FIOLABELGET, é&labelBuffer) ;} 


FIOLABELSET - Sets volume label to the string specified as newLabel. The 
string may consist of up to 11 ASCII characters: 


status = ioctl (fd, FIOLABELSET, “new.abel”") ; 


FIOATTRIBSET | | 

- Sets the file attribute byte in the DOS directory entry to 
the new value newAttrib. The fd refers to the file whose 
entry is to be modified: 


status = ioctl (fd, FIOATTRIBSET, newAttrib); 


FIOCONTIG - Allocates contiguous disk space for a file or directory. The 
number of bytes of requested space is specified in bytesRe- 
quested. In general, contiguous space should be allocated 
immediately after the file is created: 


status = ioctl (fd, FIOCONTIG, bytesRequested) ; 


FIOREADDIR - Reads the next directory entry. The argument dirStruct is 
a DIR directory descriptor. Normally, the readdir() rou- 
tine is used to read a directory, rather than using the 
FIOREADDIR function directly. See dirLib. 


DIR dirStruct; fd = open (“directory", READ); status = ioctl (fd, 
FIOREADDIR, &dirStruct) ; - 


FIOFSTATGET - Gets file status information (directory entry data). The 
argument statStruct is a pointer to a stat structure that is 
filled with data describing the specified file. Normally, 
the stat( ) or fstat() routine is used to obtain file informa- 
tion, rather than using the FIOFSTATGET function 
directly. See dirLib. _ 


struct stat statStruct; fd = open ("file", READ); status = ioctl (fd, | 
FIOPSTATGET, &statStruct) ; 
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Any other toctl() function codes are passed to the nie device driver for 
handling. 


INCLUDE FILE 
dosFsLib.h 


SEE ALSO 
ioLib, iosLib, dirLib, ramDrv, Microsoft MS-DOS Programmer's Reference 
(Microsoft Press), Advanced MS-DOS Programming (Ray Duncan, Microsoft 
Press), Programmer's Guide: I/O System, Local File Systems 


NAME 


dosFsConfigInit( ) - initialize dosFs volume configuration structure 


SYNOPSIS | 
STATUS dosFsConfiginit (pConfig, mediaByte, secPerClust, nResrvd, nFats, 
secPerFat, maxRootEnts, nHidden, changeNoWarn, autoSync) 
DOG _VOL_COMFIG *pConfig; /* pointer to volume config structure */ 


char mediaByte; |§§/* media descriptor byte */ 

char secPerClust; /* sectors per cluster */ 

short nResrvd; /* number of reserved sectors */ 

char nFats; ‘/* number of FAT copies */ 

short secPerFat) /* number of sectors per FAT copy */ 

short maxRootEnts ; /* max number of entries in root dir */ 

UINT nHidden; /* number of hidden sectors */ 

BOOL changeNoWarn; /* TRUE = disk change is unannounced */ 

BOOL autoSync; /* TRUE = sync disk during I/O */ 
DESCRIPTION 


This routine initializes a dosFs volume configuration structure 
(DOS_VOL_CONFIG). This structure is used by the dosFsDevInit{ ) routine 
to specify the file system configuration for the disk. 


The DOS_VOL_CONKFIG structure must have been allocated prior to calling 
this routine. Its address is specified by pConfig. The specified configuration 
variables are placed into their respective fields in the structure. 


This routine is provided only to allow convenient initialization of the 
DOS_VOL_CONFIG structure (particularly from the Vx960 shell). A struc- 
ture which is properly initialized by other means may be used equally well 
by dosFsDevInit{ ). 
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RETURNS 
OK, or ERROR if there is an invalid parameter or pConfig is NULL. 


SEE ALSO 
dosFsLib 
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NAME 
dosFsDateSet{ ) - set the current date 


SYNOPSIS 
STATUS dosFsDateGet (year, month, day) 
int year; /* year (1980...2099) */ 
int month; /* month (1...12) */ 
int day; /* day (1...31) */ 


DESCRIPTION 
This routine sets the current date for the dosFs file system. All files created 
or modified will have this date in their directory entries. 


SEE AiSO 
dosFsLib, dosFsTimeSet{ ), dosFsDateTimelInstall( ). 


RETURNS 
OK, or ERROR if the date is invalid. 


NAME 
dosFsDateTimelInstall( ) - install a user-supplied date/time function 


SYNOPSIS 
VOID dosFsDateTimeInstall (pDateTimeFunc) 
FUNCPTR pDeteTimeFunc; /* pointer to user-supplied function */ 


DESCRIPTION | 
This routine installs a user-supplied function to provide the current date and 
time. Once such a function is installed, dosFsLib will call it when necessary 
to obtain the date and time. Otherwise, the date and time most recently set 
by dosFsDateSet{ ) and dosFsTimeSet{ ) are used. 
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The user-supplied routine must take exactly one input parameter, the 
address of a DOS_DATE_TIME structure (defined in dosFsLib.h). The user 
routine should update the necessary fields in this structure and then return. 

_ Any fields which are not changed by the user routine will retain their previ- 
ous value. 


RETURNS 
N/A 


SEE ALSO 
dosFsLib 


NAME 
dosFsDevInit{ ) - associate a block device with dosFs file system functions 
SYNOPSIS 
DOS VOL DESC *dosFsDevinit (devName, pBlkDev, pConfig) 
char *devName; /* device name */ 
BLK DEV *palkDev; /* pointer to block device struct */ 
DOS VOL _COMFIG *pConfig; /* pointer to volume config data */ 


DESCRIPTION 
7 This routine takes a block device structure (BLK_DEV) created by a device 
driver and defines it as a dosFs volume. As a result, when high level I/O 
operations (e.g. open( ), write()) are performed on the device, the calls will 
be routed through dosFsLib. The pBlkDev parameter is the address of the 
BLK_DEV structure which describes this device. 


This routine associates the name devName with the device and installs it in 
the Vx960 I/O System's device table. The driver number used when the dev- 
ice is added to the table is that which was assigned to the dosFs library dur- 
ing dosFsInit(). (The driver number is placed in the global variable, 
dosFsDroNum.) 


The BLK_DEV structure contains configuration data describing the device 
and the addresses of five routines which will be called to read sectors, write 
sectors, reset the device, check device status, and perform other control 
functions (ioctl()). These routines will not be called until they are required 
by subsequent I/O operations. 


The pConfig parameter is the address of a DOS_VOL CONFIG structure. 
This structure must have been previously initialized with the specific dosFs 
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configuration data to be used for this volume. This structure may be easily 
initialized using the dosFsConfigInit{ ) routine. 


If the device being initialized already has a valid dosFs (MS-DOS) file sys- 
tem on it, the pConfig parameter may be NULL. In this case, the volume will 
be mounted, and the configuration data will be read from the boot sector of 
the disk. (If pConfig is NULL, both changeNoWarn and autoSync modes are 
defined as FALSE.) 


This routine allocates and initializes a volume descriptor (DOS_VOL aE) 
for the device. It returns a pointer to the DOS_VOL_DESC. | 


SEE ALSO 
dosFsLib, dosFsMkfs( ) 


RETURNS 
Pointer to volume descriptor (DOS_VOL_DESC), or NULL if there is an 
error. 


NAME | 
dosFsInit( ) - prepare to use the dosFs library 


SYNOPSIS 
STATUS dosFsInit (maxFiles) 
int maxFiles; /* max # of simultaneously open files */ 


DESCRIPTION 
This routine initializes the dosFs library. It must be called exactly once, 


before any other routine in the library. Theiargunient:specifies the number::.. 


of dosFs files that may be open at once. This routine. installs-dosFsLib as a ! 
driver in the I/O system driver table, allocates and sets up the necessary 
memory structures, and initializes semaphores. :‘The driver number assigned 
to dosFsLib is placed in the global variable, dosFsDroNum. 


To enable this initialization, define INCLUDE_DOSFS in configAILh; 
dosFsInit{ ) will then be called from the root task, usrRoot( ), in usrConfig.c. 


RETURNS 
OK, or ERROR. 


SEE ALSO 
dosFsLib 
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NAME 
dosFsMkfs( ) - initialize a device and create a dosFs file system 


SYNOPSIS 
nos _ VOL_DESC *dosFskkfs (voliiame, p&lkDev) 
char *yvolMame; /* volume name to use */ 
BLK DEV ‘*pBlkDev; /* pointer to block device struct */ 


DESCRIPTION 
This routine provides a quick method of creating a dosFs file system on a 
device. It is used instead of the two-step procedure of calling 
dosFsDevInit( ) followed by an ioctl() call with an FIODISKINIT function 
code. | 


This call uses default values for various dosFs configuration parameters (i.e., 
those found in the volume configuration structure, DOS_VOL_CONFIG). 
The values used are: 


2 - sectors per cluster (see below) 
1 - reserved sector 

2 - FAT table copies 

112 - root directory entries 

OxFO - media byte value 

0 - hidden sectors 


FALSE - changeNoWarn (disk change without notification) 
FALSE - autoSync (auto-sync mode) 


If initializing a large disk, it is quite possible that the entire disk area cannot 
be described by the maximum 64K clusters if only 2 sectors are contained in 
each cluster. In such a situation, the dosFsMkfs( ) routine will automatically 
increase the number of sectors per cluster to a number which will allow the 
entire disk area to be described in 64K clusters. 


The number of sectors per FAT table copy is set to the minimum number of 
sectors which will contain sufficient FAT entries for the entire block device. 


RETURNS | : 
Pointer to dosFs volume descriptor, or NULL if there is an error. 
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SEE ALSO 
dosFsLib 


NAME 
dosFsModeChange( ) - modify mode of dosFs volume 


SYNOPSIS | 
VOID dosFsModeChange (vdptr, nevwitode) 
DOG VOL DESC ‘vdptr; /* pointer to volume descriptor * 
int newHode; /* READ/WRITE/UPDATE (both) */ 


DESCRIPTION 
This routine sets the volume’s mode to newMode. The mode is actually kept 
in “bd_mode” fields of the the BLK_DEV structure, so that it may also be 
used by the device driver. Changing that field directly has the same result 
as calling this routine. The mode field should be updated whenever the read 
and write capabilities are determined, usually after a ready change. See the 
manual entry for dosFsReadyChange( ). 


The driver's device initialization routine should initially set the mode field to 
UPDATE (i.e., both READ and WRITE). 


RETURNS 
N/A 


SEE ALSO 
dosFsLib 


NAME 


dosFsReadyChange( ) - notify dosFsLib of a change in ready status 


SYNOPSIS 


_ word dosFsReadyChange (vdptr) 
DOS VOL_DESC ‘vdptr; /* pointer to volume descriptor */ 


1 - 58. Intel | : Rev: 30 Aug 91 


~ 


“libicies ay dosFSLib™. 


DESCRIPTION 
This routine __ sets the volume descriptor’s state to 
DOS_VD_READY_CHANGED. It should be called whenever a driver 
senses that a device has come on-line or gone off-line (e.g., a disk has been 
inserted or removed). 


After this routine has been called, the next attempt to use the volume will 
result in an attempted remount. 


This routine may also be invoked by calling ioctl({ ) with a function code of 
FIODISKCHANGE. 


Setting the “bd_readyChanged” field to TRUE in the BLK_DEV structure 
that describes this device will have the same result as calling this routine. 


RETURNS 
N/A 


SEE ALSO 
dosFsLib 


NAME 
dosFsTimeSet{ ) - set the current time | 


SYNOPSIS 
STATUE dosFsTimeset (hour, minute, second) 
int hour; /* 0 to 23 */ 
int minute; /* 0 to 59 */ 
int second; /* 0 to 59 */ 


DESCRIPTION 
This routine sets the the current time for the dosFs file system. All files 
created or modified will have this date in their directory entries. 


RETURNS | 
OK, or ERROR if the time is invalid. 


SEE ALSO 
dosFsLib, dosFsDateSet ), dosFsDateTimelInstall( ) 
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NAME | 
dosFsVolUnmount{ ) - unmount a dosFs volume 


SYNOPSIS 
STATUS doeFsVolUnmount (vdptr) 
DOS VOL_DESC ‘*vdptr; /* pointer to volume descriptor * 


DESCRIPTION 
This routine is called when I/O operations on a volume are to be discontin- 
ued. This is the preferred action prior to changing a removable disk. 


All buffered data for the volume is written to the device (if possible, with no 
error returned if data cannot be written), any open file descriptors are 
marked as obsolete, and the volume is marked as not currently mounted. 
When a subsequent I/O operation is initiated on the disk (e.g., during the 
next open({ )), the volume will be remounted automatically. 


Once file descriptors have been marked as obsolete, any attempt to use them 
for file operations will return an error. (An obsolete file descriptor may be 
freed by using close(). The call to close() will return an error, but the 
descriptor will in fact be freed.) File descriptors obtained by opening the 
entire volume (in raw mode) are not marked as obsolete. 


This routine may also be invoked by calling ioctl() with the FIOUN- 
MOUNT function code. 


This routine must not be called from interrupt level. 


RETURNS 
OK, or ERROR, if the volume was not mounted. 


SEE ALSO 
dosFsLib, dosFsReadyChange( ) 
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NAME 


dsm960Lib - Vx960/80960 disassembler 


SYNOPSIS 
dsm960Inst() - disassemble Intel i960 object code. 


int dsm960Inst (pMem, adrs, prtAdrs) 


DESCRIPTION 
This library has all the routines and data structures necessary to print 1960 
object code in assembly language format. The programming interface is via 
dsm960Inst, which prints a single disassembled instruction. To disassemble 
from the shell, use the 1 command, which calls this library to do the actual 
work. See dbgLib for details. 


ADDRESS PRINTING ROUTINE 
Many of the operands to assembly language instructions are addresses. In 
order to allow the ability to print these symbolically, the call to dsm960Inst 
has, as a parameter, the address of a routine to call to print an address. 
When dsmLib needs to print an address as part of an operand field, it will 
call the supplied routine to do the actual printing. The routine should be 
declared as: 


VOID prtAddress (address) 
int address; * address to print * 


When called, the routine should print the address on standard out (with 
printf or whatever) in whatever form, numeric or symbolic, that it desires. 
The routine used by I, for instance, looks up the address in the system sym- 
bol table and prints the symbol associated with it, if there is one. If not, it 
just prints the address as a hex number. 


If the prtAddress argument to dsmPrint is NULL, a default print routine is 
used, which just prints the address as a hex number. 


INCLUDE FILE 
dsmLib.h 
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NAME 
dsim960Inst()- disassemble i960 object code. 
SYNOPSIS : | 
int dsm960Inst (pMem, adrs, prtAdrs) 
UINT32 *pMem; /* location to disassemble */ 
UINT32 adrs}; /* preappend adrs for printing */ 
FUNCPTR prtAdrs; /* adrs printing function */ 
DESCRIPTION 


This routine is called to disassemble and print (on standard out) a single 
instruction. The function passed as parameter prtAddress will be used to 
print any operands which might be construed as addresses. This could be 
either a simple routine that just prints a number, or one that looks up the 
address in a symbol table. The disassembled instruction will be prepended 
with the address passed as a parameter. 


If prtAddress == 0, a default routine will be used that prints addresses as 
hex numbers. 


RETURNS 
The number of 32-bit words occupied by the instruction. 


SEE ALSO 
dsm960Lib 
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NAME 


SYNOPSIS 


errnoLib - error status library 


errnoGet( ) - get the error status value of the calling task 
errnoOfTaskGet( ) - get the error status value of a specified task 
errnoSet( ) - set the error status value of the calling task 
errnoOfTaskSet( ) - set the error status value of a specified task 


int errnoGet () 

int errnoOfTaskGet (taskId) 

STATUS exrrnoSet (errorValue) 

STATUS errnoOfTaskSet (taskId, errorvalue) 


DESCRIPTION 


This library contains routines for setting and examining the error status 
values of tasks and interrupts. Most Vx960 functions return ERROR when 
they detect an error, or NULL in the case of functions returning pointers. In 
addition, they set an error status that elaborates the nature of the error. 


This facility is compatible to the UNIX error status mechanism in which 
error status values are set in the global variable errno. However, in Vx960 
there are many task and interrupt contexts that share common memory 
space and therefore conflict in their use of this global variable. Vx960 
resolves this in two ways: 


(1) For tasks, Vx960 maintains the errno value for each context separately, 
and saves and restores the value of errno with every context switch. 
The value of errno for a non-executing task is stored in the task’s TCB. 
Thus, regardless of task context, code can always reference or modify 
errno directly. 


(2) For interrupt service routines, Vx960 saves and restores errno on the 
interrupt stack as part of the interrupt enter and exit code provided 
automatically with the intConnect() facility. Thus, interrupt service 
routines can also reference or modify errno directly. 


The errno facility is used throughout Vx960 for error reporting. In situations 
where a lower-level routine has generated an error, by convention, higher- 
level routines propagate the same error status, leaving errno with the value 
set at the deepest level. Developers are encouraged to use the same 
mechanism for application modules where appropriate. 
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ERROR STATUS VALUES 


An error status is a 4-byte integer. By convention, the most significant two 


_ bytes are the module number, which indicates the module in which the error 


occurred. The lower two bytes indicate the specific error within that _ 
module. Module number 0 is reserved for UNIX error numbers so that 
values from the UNIX errno.h header file can be set and tested without 
modification. Module numbers 1-500 decimal are reserved for Vx960 


modules. These are defined in vwModNum.h. All other module numbers 


are available to applications. 


PRINTING ERROR STATUS VALUES 


1-64 


Vx960 can include a special symbol table called statSymTbl which 
printErrno({ ) uses to print human-readable error messages. 


This table is created with the tool makeStatTbl in vw/bin. This tool reads all 
the .h files in a specified directory and generates a C-language file, which 
generates a symbol table when compiled. Each symbol consists of an error 
status value and its definition, which was obtained from the header file. 


For example, suppose the header file vw/h/myFile.h contains the line: 
#define S_myFile_ERROR_TOO MANY_COOKS 0x230003 


The table statSymTbl is created by first running: 
makeStatTbl vw/h >statTbl.c 
This creates a file statTbl.c, which, when compiled, generates statSymITOl. 


The table is then linked in with Vx960. These steps are normally done 
automatically by the vw/config/all makefile. 


If the user now types from the Vx960 shell: 
-> printErrno 0x230003 


The printErrno( ) routine would respond: 


S myFile_ERROR_TOO MANY COOKS 


The makeStatTbIl tool looks for error status lines of the form: 


#define § xxx <n> 


where xxx is any string, and n is any number. All Vx960 status lines are of 
the form: 


fdefine S_thisFile_MEANINGFUL_ERROR_MESSAGE Oxnnnn 


where thisFile is the name of the module. 
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This facility is available to the user by adding header files with status lines 
of the appropriate forms and remaking Vx960. 


INCLUDE FILES 
The file vwModNum.h contains the module numbers for every Vx960 
module. The include file for each module contains the error numbers which 
that module can generate. 


SEE ALSO 
printErrno( ), makeStatTbl, Programmer's Guide: Basic OS 


NAME 
errnoGet( ) - get the error status value of the calling task 
SYNOPSIS 
int errnoGet () 
DESCRIPTION 
This routine gets the error status stored in errno. It is provided for compati- 
bility with previous versions of Vx960 and simply accesses errno directly. 
RETURNS | 
The error status value contained in errno. 
SEE ALSO | 


ermoLib, errnoSet( ), errnoOfTaskGet{ ) 


NAME 
errnoOfTaskGet( ) - get the error status value of a specified task 


SYNOPSIS 
int errnoOfTaskGet (taskId) 
int taskId; /* task ID, O means current task */ 


DESCRIPTION 
This routine gets the error status most recently set for a specified task. If 
taskId is zero, the calling task is assumed, and the value currently in errno is 
returned. 
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This routine is provided primarily for debugging purposes. Normally, tasks 
access errno directly to set and get their own error status values. 


RETURNS | 
The error status of the specified task, or ERROR if the task does not exist. 


SEE ALSO 
errmoLib, errnoSet( ), errnoGet( ) 


NAME 
errnoSet( ) - set the error status value of the calling task 


SYNOPSIS 
STATUS errnoSet (errorValue) 
int errorValue; /* error status value to set */ 


DESCRIPTION | 
This routine sets the errno variable with a specified error status. It is pro- 
vided for compatibility with previous versions of Vx960 and simply accesses 
errno directly. 


RETURNS 
OK, or ERROR if the interrupt nest level is too deep. 


SEE ALSO 
ermoLib, errnoGet{ ), errnoOfTaskSet{ ) 


NAME 
errnoOfTaskSet( ) - set the error status value of a specified task 


SYNOPSIS 
STATUS errnoOfTaskSet (taskId, errorValue) 
int taskId; /* task ID, O means current task */ 
int errorValue; /* error status value */ 


DESCRIPTION 
This routine sets the error status for a specified task. Lf taskId is zero, the cal- 
ling task is assumed, and errno is set with the specified error status. 


1 - 66 Intel a Rev: 29 Aug 91 


This routine is provided primarily for debugging purposes. Normally, tasks 
access errno directly to set and get their own error status values. 


RETURNS 
OK, or ERROR if the task does not exist. 


SEE ALSO 
ermoLib, errnoSet( ), erruoOfTaskGet( ) 
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NAME 


etherLib - Ethernet raw I/O routines and hooks 


SYNOPSIS 
etherOutput() - send a packet on an Ethernet interface 
etherInputHookAdd( ) - add a routine to receive all Ethernet input packets 
etherOutputHookAdd( ) - add a routine to receive all Ethernet output packets 
etlterAddrResolve( ) - resolve an Ethernet address for a given Internet address 


STATUS etherOutput (pIf, pEtherHeader, pData, dataLength) 

STATUS etherInputHookAdd (inputHook) 

STATUS etherOutputHookAdd (outputHook) 

STATUS etherAddrResolve (pIf, targetAddr, eHdr, numTries, numTicks) 


DESCRIPTION 

This module provides utilities that give direct access to Ethernet packets. 
Raw packets can be output directly to an interface using etherOutput( ). 
Incoming and outgoing packets can be examined or processed using the 
hooks etherInputHookAdd() and etherOutputHookAdd( ). The input hook 
can be used to receive raw packets that are not part of any of the supported 
network protocols. The input and output hooks can also be used to build 
network monitoring and testing tools. 


Normally the network should be accessed through the higher level socket 
interface provided in sockLib. The routines in etherLib should rarely, if 
ever, be necessary for applications. 


CAVEAT 
Most Vx960 network drivers, even if they are not truly Ethernet, are still 
accessible via these routines. These drivers include: 


- Backplane 

- Intel 82596 LAN coprocessor 

- CMC ENP-10 Ethernet 

- Excelan EXOS 202 and 302 Ethernet 

- LANCE (AMD 7990) Ethernet 

- National Semiconductor NIC Chip (DP8390) Ethernet 


However, the following Vx960 network drivers are not accessible via these 
routines: 


- Sun-3/E Ethernet 
- Integrated Solutions Ethernet 
- SLIP | 


1-68 Intel Rev: 29 Aug 91 


Librarles (1) etherLib 


SEE ALSO 
Programmer's Guide: Network 


NAME 
etherOutput( ) - send a packet on an Ethernet interface 
SYNOPSIS 
STATUS etherOutput (pIf, pEtherHeader, pData, dataLength) 
struct ifnet “pif; /* interface on which to send */ 
struct ether header ‘*pEtherHeader; /* ethernet header to send “7 
char *pData; /* data to send «/ 
int dataLength; /* # of bytes of data to sand */ 
DESCRIPTION 


This routine sends a packet on the specified Ethernet interface by calling the 
interface’s output routine directly. 


The first argument pIf is a pointer to a variable of type struct ifnet which con- 
tains some useful information about the network interface. A routine 
named ifunit() can retrieve this pointer from the system in the following 
Way: 


struct ifnet “pIf; 


prf = ifunit (“ln0"); 


If ifunit( ) returns anon NULL pointer, it is a valid pointer to the named net- 
work interface device structure of type struct ifnet. In the above example, pIf 
points to the data structure that describes the first LANCE network interface 
device if ifusit( ) is successful. 


The second argument pEtherHeader should contain a valid Ethernet address 
of the machine for which the message contained in the argument pData is 
intended. If the Ethernet address of this machine is fixed and well-known to 
the user, filling in the structure ether_header can be accomplished by using 
bcopy() to copy the six-byte Ethernet address into the ether_dhost field of 
the structure ether_header. Alternatively, users can make use > of the routine 
etherAddrResolve() which will use ARP (Address Resolution Protocol) to 
resolve the Ethernet address for a given Internet Address. _ | 
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RETURNS : 
OK, or ERROR if the routine runs out of mbufs. 


SEE ALSO 
etherLib, etherAddrResolve{( ) 
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NAME 
etherInputHookAdd{ ) - adda routine to receive all Ethernet input packets 


SYNOPSIS 
STATUS etherInputHookAdd (inputHook) 
FUNCPTR inputHook; /* routine to receive ethernet input */ 


DESCRIPTION 
This routine adds a hook routine that will be called for every Ethernet 
packet that is received. 


The calling sequence of the input hook routine is: 


BOOL inputHook (pIf, buffer, length) 
struct ifnet *pIf; /* ptr to interface packet was received on * 
char *buffer; /* ptr to received packet * 
int length; /* length of received packet * 


The hook routine should return TRUE if it has handled the input packet and 
no further action should be taken with it. It should return FALSE if it has 
not handled the input packet and normal processing (e.g., Internet) should 
take place. 


The packet is in a temporary buffer when the hook:-routine is called: This 
buffer will be reused upon return from the hook. If the hook routine needs 
to retain the input packet, it should copy it elsewhere. 


IMPLEMENTATION . 
A call to efherInputHookRtn should be invoked in the receive routine of every 
network driver providing this service. For example: 


#include “etherLib.h”" 
xxxRecv () 


/* call input hook if any * 
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if ((etherInputHookRtn != NULL) && 
(* etherInputHookRtn) (&ls->ls if, (char *)eh, len)) 
{ 
return; /* input hook has already processed this packet * 
} | 
RETURNS 
OK (always). 


SEE ALSO 
etherLib 


NAME 


etherOutputHookAdd() - add a routine to receive all Ethernet output pack- 
ets , 


SYNOPSIS 
STATUS etherOutputHookAdd (outputHook) 
FUNCPTR outputHook; /* routine to receive ethernet output */ 


DESCRIPTION 
This routine adds a hook routine that will be called for every Ethernet 


packet that is transmitted. 
The calling sequence of the output hook routine is: 


BOOL outputHook (pIf, buffer, length) 
struct ifnet *pIf; /* ptr to interface packet will be sent on * 
char tbuffer; /* ptr to packet to be transmitted _  # 
int length; /* length of packet to be transmitted “o 


The hook is called immediately: before transmission. The hook routine 
should return TRUE if it has handled the output packet and no further 
action should be taken with it. It should return FALSE if it has not handled 
the output packet and normal transmission should take place. 


The Ethernet packet data is in a temporary buffer when the hook routine is 
called. This buffer will be reused upon retum from the hook. If the hook 
routine needs to retain the output packet, it should be copied elsewhere. 


IMPLEMENTATION 
A call to etherOutputHookRin should be invoked in the transmit routine of 
every network driver providing this service. For example: 
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finclude “etherLib.h” 
xxxStartOutput () | 
/* call output hook if any * 
if ((etherOutputHookRtn I= NULL) && 
(* etherOutputHookRtn) (&ls->ls_if, buf0, len)) 


{ 
/* output hook has already processed this packet * 


} 


else 


RETURNS 
OK (always). 


SEE ALSO 
etherLib 


NAME 
etherAddrResolve() - resolve an Ethernet address for a given Internet 
address 
SYNOPSIS 
STATUS etherAddrResolve (pIf, targetAddr, eHdr, numTries, numTicks) 
struct ifnet ‘*pIf; /«* interface on which to send ARP req */ 
char *targetAddr; /* name or Internet address of target */ 
char *eHdr} /* where to return the ethernet addr */ 
int num(ries} /* number of times to try ARP’ing */ 
int numTicks; /* number of ticks between ARP‘ing */ 
DESCRIPTION 


This routine uses the ARP (Address Resolution Protocol) and internal ARP 
cache to resolve the Ethernet address of a machine that owns the Internet 
address given in targetAddr. 


The first argument pIf is a pointer to a variable of type struct ifnet which 
identifies the network interface through which the ARP request messages 
are to be sent out. The routine ifunit() is used to retrieve this pointer from 
the system in the following way: 


struct ifnet *pIf; 
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prf = ifunit (“1n0"); 


If ifunit() returns a non-NULL pointer, it is a valid pointer to the named net- 
work interface device structure of type struct ifnet. In the above example, pl/f 
will be. pointing to the data structure that describes the first LANCE net- 
work interface device if ifunit( ) is successful. 


The six-byte Ethernet address is copied to eHdr, if the resolution of far- 
getAddr is successful. eHdr must point to a buffer of at least 6 bytes. 


RETURNS 
OK if the address is resolved successfully, or ERROR if eHdr is NULL, 


targetAddr is invalid, or address resolution is unsuccessful. 


SEE ALSO 
etherLib, etierOutput( ) 
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NAME 
exc960Lib - architecture-dependent exception handling: i960 


SYNOPSIS | : 

excVecInit( ) - initialize exception/interrupt vectors 

excInfoShow( ) - display exception information 

excNMIHookAda{ )- adda HOOK) routine to be called in the event of an NMI. 


STATUS excVecInit () 
VOID excInfoShow (pExcInfo, taskId) 
FUNCPTR excNMIHookAdd (pHook) 


DESCRIPTION 
This module contains the architecture-dependent portions of the exception 
handling facilities. See excLib for the portions that are architecture indepen- 
dent. 


NAME 
excVecInit{ ) - initialize exception/interrupt vectors 


SYNOPSIS 
STATUS excVecInit () 


DESCRIPTION 
This routine sets all fault vectors to point to the appropriate default fault 
handlers. The i960 fault-table is filled-with-a-default -fault handler, and all 
non-reserved vectors in the i960 interrupt table are filled with a default inter- 
rupt handler. 


WHEN TO CALL 
This routine is usually called from the system startup routine, usrInit() in 
usrConfig, before interrupts are enabled. 


RETURNS 
OK (always). 


SEE ALSO 
exc960Lib 
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NAME 


excInfoShow( ) - display exception information 


SYNOPSIS 
VOID excInfoShow (pExcInfo, taskId) 
EXC_INFO *pExcInfo; 


UINT32 taskId; 
DESCRIPTION 
Display information associated with an interrupt or fault. 
SEE ALSO 
exc960Lib 


NAME 
excNMIHookA dd( ) - add a hook routine to be called in the event of an NMI. 
SYNOPSIS | 
FUNCPTR excNMIHookAdd (pHook) 
FUNCPTR pHook; /* pointer to hook routine */ 
DESCRIPTION 
This routine adds a hook routine tobe called in the event of a non-maskable 
interrupt. Note that only the 80960CA supports NMIs. 
RETURNS 
pointer to previous hook routine.?:<: :- 
SEE ALSO 
exc960Lib 
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NAME , 
excLib - exception handling facilities 


SYNOPSIS 
excInit( ) - initialize the exception handling package | 
excHookAdd( ) - specify a routine to be called with exceptions 
excTask( ) - handle task-level exceptions 


STATUS excInit () 
VOID excHookAdd (excepHook) 
VOID excTask () 


DESCRIPTION 
This module provides facilities for handling exceptions. It safely traps and 
reports exceptions caused by program errors in Vx960 tasks, and it reports 
occurrences of interrupts that are explicitly connected to other handlers. 


INITIALIZATION 
Initialization of excLib facilities is in two parts. First, the routine 
excVecInit{ ) is called to set all the i960 fault vectors to the default handlers 
provided by this module. Since this does not involve Vx960’ kernel facilities, 
it is usually done early in the system start-up routine usrInit( ) in the library 
usrConfig with interrupts disabled. 


The rest of this package is initialized by calling excInit( ), which spawns the 
exception support task, excTask(), and creates the pipe used to communi- 
cate with it. Since this initialization uses Vx960’ kernel facilities and the pipe 
driver, it must be performed in the root task usrRoot() in the library 
usrConfig after the pipe driver has been installed. 


Exceptions or uninitialized interrupts that occur after the vectors have been 
initialized by excVecInit, but before exclInit is called, cause a trap to the ROM 
monitor. 


NORMAL EXCEPTION HANDLING 

When a program error generates an exception (such as divide by zero, or a 
bus or address error), the task that was executing when the error occurred is 
suspended, and a description of the exception is displayed on standard out- 
put. The Vx960 kernel and other system tasks continue uninterrupted. The 
suspended task can be examined with the usual Vx960 routines, including 
ti( ) for task information and ftt{ ) for a stack trace. It may be possible to fix 
the task and resume execution with tr{). However, tasks aborted in this 
way are often unsalvageable and can be deleted with td( ). 
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When an interrupt that is not connected to a handler occurs, the default 
handler provided by this module displays a description of the interrupt on 
standard output. 


ADDITIONAL EXCEPTION HANDLING ROUTINE 
The routine excHookAdd() adds a routine that will be called when a 
hardware exception occurs. This routine is called at the end of normal 
exception handling. 


TASK-LEVEL SUPPORT 
The routine excInit() spawns the task excTask() to perform special excep- 
tion handling functions that need to be done at task level. Do not suspend, 
delete, or change the priority of excTask( ). 


DBGLIB 
The facilities of excLib, including excTask( ), are used by dbgLib to support 
breakpoints, single-stepping, and additional exception handling functions. 


SIGLIB 
A higher level UNIX-compatible interface for hardware and software excep- 
tions is provided by sigLib. If sigvec() is used to initialize the appropriate 
hardware exception/interrupt (e.g., BUS ERROR == SIGSEGV), excLib will 
use the signal mechanism instead. 


SEE ALSO 
dbgLib, sigLib, intLib, Programmer's Guide: Debugging 


NAME 
excInit( ) - initialize the exception handling package 


SYNOPSIS 
STATUS excInit () 


DESCRIPTION | 
This routine installs the exception handling facilities and spawns excTask{ ), 
which handles exception handling functions that need to be done at task 
level. It also creates the message queue used to communicate with 
excTask{ ). 


WHEN TO CALL 
Install the exception handling facilities as early as possible in system initiali- 
zation in the root task usrRoot{( ) in usrConfig. 
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RETURNS 
OK, or ERROR if a message queue cannot be created or excTask( ) cannot be 
spawned. | 


SEE ALSO 
excLib, excTask{ ) 


NAME 


excHookAdd( ) - specify a routine to be called with exceptions 


SYNOPSIS 
VOID excHookAdd (excepHook) 
FUNCPTR excepHook; /* routine to be called when exceptions occur */ 


DESCRIPTION 
This routine specifies a routine that will be called when hardware exceptions 
occur. This routine is called after normal exception handling, which 
includes suspending the task that incurred the error and displaying informa- 
tion about the error. 


The exception handling routine should be declared as: 


VOID myHandler (task, vecNum, pEsf) 
int task; /* id of offending task */ 
int vecNum; /* exception vector number */ 
ESFO *pEsf; /* pointer to exception stack frame */ 


where task is the ID of ‘the: task that was running when the exception 
occurred. 


This facility is normally used by dbgLib( ) to activate its exception handling 
mechanism. If an application provides its own exception handler, it will 
supersede the dbgLib mechanism. 


SEE ALSO 
excLib 


1-78 Intel | | Rev: 29 Aug 91 


le a - 
A . ° . . .. - . 
ae re a Sig Teste oe bie ee Cane 
wee et a eh ae eR Ca gee. ob fees el Cae re. eB, tees aaa —— Sys . . seo. 
. .* a . ° aoe we F m eo - ; . Cosas 
Pies oe bo ES Ce EE Ta Ss voy Bae pei er eee Oe AS ayy 8 
a : 2 oo. Po eta g ; og ee ett 3 ghee Ae te ae. ol te, 2 ap ae , P A aeeee ly . totes ay « SE hia 
had be r} Cweery s a oe o. ee . boy 1 e ee “ ‘ ° . . . ” i 
i ars en) SR fit ore rie heer, ° . wet Balke 
rear 3087 eo ' Sete seats | we < ee : ° ee --* . . 
gooey or ee Seine ee tee ioe gy, TRS ag TN TF eng a tae ae ete teen Seen ge “e os ‘i 
is Gee 138 ; . aes : : eG : . Per 
cept 3 > ‘ . fo Ghia are Seren a arr: ae ae re oe ee 
PHP Pye Pg lege ah : byes . as ee ET Ot Oe ee 
. . .° . . be . a 8 . im ve oe sae aa 
’ ae aes ‘ t 2 . fi * ge SE Oe Bd 
: Pi : ° 4, * omar oo ., s . 
Py : . * ¢ . i 
he: se ue és Sicns Wad shtle, gist Waniviecn Suabet reed Cif 0, S0% seit 
. = . 7 ‘ aN we 7 “ ‘ 5 7 ; 
: c . o- 


SANS 
NS 


SHEN set rence 
BARES ee ee steep 
SS es 


NANTES 
ms eaten 


onc a em 
AenAtetetocmnncet x 
4 ,. me mane < 
sheerrnttianas Shee 


ont cael: Nretasetaceres Wh sae: rN Bee Aes cette tmtasyretareestates close ketectesesstaterencottetats aN ere tat nredeteNesnsecaretemenstatsoteerevsereeat Ne NT raraveltatatetntetaentetatetenteaterenaeree onece ere eee aseeeet eee eas totatorecr snes Rake SENS tetatabatahe’ 
RESONANT : : ONS : BERR RC ONCE EEOS 


NAME. 
excTask( ) - handle task-level exceptions 


SYNOPSIS 
VOID excTask () 


DESCRIPTION 
This routine is spawned as a task by excInit( ) to perform functions that can- 
not be performed at interrupt or trap level. It has a priority of 0. Do not 
suspend, delete, or change the priority of this task. | 


SEE ALSO 
excLib, excInit( ) 
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NAME | 
fioLib - formatted I/O library 


SYNOPSIS 
printf() - print a formatted string to standard output 
printErr( ) - print a formatted string to standard error 
fdprintf() - print a formatted string to a specified file descriptor 
sprintf() - put a formatted string in a specified buffer 
vprintf( ) - print a formatted string with a variable argument list to standard output 
ufdprintf( ) - print a formatted string with a variable argument list to a specified fd 
vsprintf( ) - put a formatted string with a variable argument list in a specified buffer 
fioFormatV() - convert a format string 
sscanf() - obtain values for arguments from an ASCII string 
fioRead() - read a buffer 
fioRdString( ) - read a string from a file 


int printf (fmt, ...) 

int printErr (fmt, ...) 

int fdprintf (fd, fmt, ...) 

int sprintf (buffer, fmt, ...) 

int vprintf£ (fmt, vaList) 

dnt vfdprintf (fd, fmt, vaList) 

int vsprintf£ (buffer, fmt, vaList) 
int filoFormatVv (fmt, vaList, outRoutine, outarg) 
int sscanf (str, fmt, ...) 

int fioRead (fd, buffer, maxbytes) 
int floRdString (fd, string, maxbytes) 


DESCRIPTION | 
This library provides the basic formatting and scanning I/O functions. It 
includes the ANSI-compliant printf() and scanf() family of functions. It 
also includes several utility routines. 


If the floating-point format specifications e, f, and g are to be used with 
these routines, the routine floatInit{) must be called first. If the 
INCLUDE_FLOATING POINT option is defined in configAII.h, this is done 
by the root task usrRoot( ) in usrConfig.c. | 


These routines do not use the buffered I/O facilities provided by stdioLib. 
Thus, they can be invoked even if the buffered stdio package has not been 
included, and even if the calling task was not created with the VX_STDIO 
task option. This includes printf(), which in most UNIX systems is part of 
the buffered I/O facilities. Because printf() is so commonly used, it has 
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been implemented as an unbuffered I/O function. This allows minimal for- 
matted I/O to be achieved without the overhead of the entire stdioLib pack- 
age. See the manual entry for stdioLib for more details. 


SEE ALSO 
stdioLib, floatLib, Programmer's Guide: I/O System 


NAME 
printf() - print a formatted string to standard output 
SYNOPSIS 
int printf (fmt, ...) 
char ‘*fmt; /* format string for print «/ 
DESCRIPTION 


This routine prints formatted strings to standard output. The string fint con- 
tains ordinary characters, which are copied to standard output, and conver- 
sion specifications. The conversion specifications cause the arguments that 
follow fmt to be converted and printed as part of the formatted string. The 
number of arguments is arbitrary, but they must correspond to the conver- 
sion specifications in fit. 


This routine is compatible with the ANSI specification for printf{( ) formats. 


The format string contains normal ASCII text, which is passed as is, except 
for special conversion specifications of the following form: 


t<-><+><sp><#><0><n><.n><[h1L]>[(d]ijulo]x|x|p|c]s|ble|£]g]n) 


-  - Left-justify converted argument in its field. 

+ - Precede a signed conversion with a sign. 

sp - Precedea signed conversion with a sign, or with a blank if positive. 
- Print the result in an alternate form. 

QO ~- Fill leading spaces with zeros. 


n - Minimum field width. If the converted argument is shorter than the 
field width, it will be padded on the left (or right if left-adjustment is | 
indicated). If the field width is specified as * instead of an integer, 
then the field width will be obtained from the next (integer) argument 
in sequence. Thus a field specification with an * for field width con- 
sumes an additional argument. 
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- Precision. For floating point formats, specifies the number of digits 


after the decimal point (f), or number of significant digits total (g). 
For strings (s) ), specifies the maximum number of characters to for- 
mat. A precision can be specified as an * instead of an integer, in 
which case, the precision will be obtained from the next (integer) 
argument in sequence. Thus a field specification with an * for preci- 
sion consumes an additional argument. 


Indicate that a corresponding data item is a short (h) or long (1 or L) 
rather than an int. 


Convert the argument to signed decimal notation. 

Same as d. | 

Convert the argument to unsigned decimal notation. 
Convert the argument to unsigned octal notation. 
Convert the argument to unsigned hexadecimal notation. 
Same as x but with upper case letters (A-F). 


Convert the argument to system-dependent “‘pointer’ representation 
(in Vx960, same as x with leading “’0x’’). 


Print a single-character argument. 


Print a string argument; characters are printed until a null or max- 
imum field width is reached. 


Print a buffer argument, characters are printed until minimum field 
width is reached. 


Print a float argument in the style:“[-]d.ddde+dd”, where there is one 
digit before the decimal point and the number after is equal to the 
precision specification forthe argument. ‘When the precision is miss- 
ing, six digits are peter ‘byvan-1, the argument is a_ 
double. 


Print a float argument in:the style:“‘[-]}ddd:ddd”, where the number of 
ds after the decimal point. is. equal to the ‘precision specification for 


the argument. If the precision is missing,.six digits are given; if the 


precision is explicitly 0, no digits and no decimal point are printed. If 
preceded by an 1, the argument is a double. 


Convert a float to either e or f, whichever is more compact. 


Store number of characters printed so far in the integer pointed to by 
the next argument in sequence. 
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RETURNS 
The number of characters output, or ERROR if there is an error in the out- 
put. 


SEE ALSO . 
fioLib, ANSI C specification for printf( ) formatting 


NAME 
printErr( ) - print a formatted string to standard error 


SYNOPSIS 
int printErr (fmt, ...) 
char *fmt; /* format string for print */ 


DESCRIPTION | 
This routine is exactly like printf( ), except that it sends output to standard 
error. 


SEE ALSO | 
fioLib, printf() 


NAME 


fdprintf() - printa formatted string to:a’specified file descriptor ° 


SYNOPSIS 
int fdprintf (fd, fmt, ...) ea 
int fd; /* £€d to which to print : */ 
char *fmt; /* format string for print */ 


DESCRIPTION 
This routine is exactly like printf(), except that it sends its output to the 
specified fd rather than to standard output. 


SEE ALSO 
fioLib, printf{ ) 
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NAME , 
sprintf() - put a formatted string in a specified buffer 


SYNOPSIS 
int sprintf (buffer, fmt, ...) 
char ‘*buffer; /* buffer to receive decoded text */ 
char *fmt; /* format string */ 


DESCRIPTION 
This routine is exactly like printf(), except that it copies its output to buffer, 
rather than to standard output. The buffer is null-terminated. 


RETURNS 
The number of characters copied to buffer, not including null termination. 


NOTE 
This routine has changed to be ANSI compatible. Previous Vx960 versions 
of sprintf() returned the number of characters put into buffer including the 
null termination. The ANSI C standard specifies that the null character 
should not be included in the returned count. Thus, the return value will be 
one less than in previous versions. 


SEE ALSO 
fioLib, printf) 


NAME 
uprintf( ) - print a formatted string with a variable argument list to standard 
output 
SYNOPSIS 
int vprintf (fmt, vaList) 
char * fmt 3 /* format string for print «/ 
va_list vaList; /* optional arguments to format */ 
DESCRIPTION 


This routine is exactly like printf(), except that it takes the variable argu- 
ments to be formatted as a list of type va_list rather than as in-line argu- 
ments. | 
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NAME 
v*dprintf{(.) - print a formatted string with a variabic argument list to a speci- 
fied fd 
SYNOPSIS 
int vfdprintf (fd, fmt, vaList) 
int fd; /* £d to which to print */ 
char * £mt 3 /* format string for print */ 
va_list vaList; /* optional arguments to format */ 
DESCRIPTION 


This routine is exactly like fdprintf(), except that it takes the variable argu- 
ments to be formatted as a list of type va_list rather than as in-line argu- 
ments. 


SEE ALSO 
fioLib, fdprintf( ) 


NAME 
usprintf{() - put a formatted string with a variable argument list in‘a speci- 
fied buffer 
SYNOPSIS 
int vsprintf (buffer, fmt, vaList) 
char “buffer; /* buffer to receive decoded text */ 
char * fmt ; /* format string */ 
va_list vaLlist; /* optional arguments to format */ 
DESCRIPTION 


This routine is exactly like sprintf(), except that it takes the variable argu- 
ments to be formatted as a list of type va_list rather than as in-line argu- 
ments. 
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SEE ALSO 
fioLib, sprintf() 


NAME 
fioFormatV( ) - convert a format string 
SYNOPSIS 
int fioFormatv (fmt, vaList, outRoutine, outarg) 
char * fmt}; /* format string */ 
va_list vaList; /* pointer to list of varargs list «/ 
FUNCPTR outRoutine; /* routine to handle args as they’re formatted */ 
int outarg; /* argument to routine «/ 
DESCRIPTION 
This routine is used by the printf( ) family of routines to handle the actual 
conversion of a format string. The first argument is a format string, as 
described in the entry for printf(). The second argument is a variable argu- 
ment list vaList that was previously established. 
As the format string is processed, the result will be passed to the output rou- 
tine whose address is passed as the third parameter, outRoutine. This out- 
put routine may output the result to a device, or put it in a buffer. In addi- 
tion to the buffer and length to output, the fourth argument, outarg, will be 
passed through as the third parameter to the output routine. This parameter 
could be an fd, a buffer address, or any other value that can be passed in an 
“int”, 
The output routine should be declared.as follows: = «: 
STATUS outRoutine (buffer, nchars, outarg) 
char “buffer; /* buffer passed to routine ; = / 
int nchars; /* length of buffer ee / 
int outarg; /* arbitrary argument saagad to */ 
/* format routine «/ 
The output routine should return OK if successful, or ERROR if unsuccess- 
ful. 
RETURNS 
The number of characters output, or ERROR if the output routine returned 
ERROR. 
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SEE ALSO 
fioLib 


NAME 
sscanf() - obtain values for arguments from an ASCII string 


SYNOPSIS 
int sscanf (str, fmt, ...) 
char “str; /* string to scan */ 
char “fmt; /* the format string */ 


DESCRIPTION 
This routine reads characters from the string str, interprets them according 
to format specifications in the string fmt, and assigns values to the argu- 
ments. 


This routine is compatible with ANSI specification for scanf() formats. 


The format string can contain white-space characters (space, tab, carriage 
return, newline, and form-feed), which are ignored, and ordinary characters 
(not %). Ordinary characters are expected to match the next non-white- 
space character in the string str. 7 


Conversion specifications are of the following form: 
[t<*><n><h | l>(d[ifulo|x]x|c|sle[fi|g/El/FiG]r...)] 


* _ + Suppress assignment. If present, will cause noate be. scanned: but.no:: 
assignment to arguments. 8 
n  - Anoptional number specifying a maximum field width.,: «a -- 
h|1 - An optional character indicating that the value convérted is‘ tobe. 
assigned to a short (h) or long (1) integer or a double (1) precision float. 


d  - A decimal integer is expected in the input; the corresponding argu- 
ment should be a pointer to an integer (short or long). 


i - An integer is expected in the input. The input may be a decimal, hex, 
or octal character as determined by a leading prefix of “0” (octal) or 
“0x (hex). The corresponding argument should be a pointer to an 
integer (short or long). 


u-_—- - A decimal integer is expected in the input; the corresponding argu- 
ment should be a pointer to an unsigned integer (short or long). 
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o - Anoctal integer is expected in the input; the corresponding argument | 


ber 2 


should be a pointer to an integer (short or long). 


A hexadecimal integer is expected in the input; the corresponding 
argument should be a pointer to an integer (short or long). 


A character is expected in the input; the corresponding argument 
should be a character pointer. If a field width is given, the argument 
should be an array. 


A character string is expected, delimited by white space, a field width 
specification, or an EOS; the corresponding argument should be a 
character pointer, pointing to a character array large enough to accept 
both the string and a terminating NULL, which will be added. 


A character string is expected, delimited by any character not con- 
tained in the bracketed string. The left bracket is followed by a set of 
characters and a right bracket. The characters between the brackets 
define a set of characters making up the string. If the first character is 
not a circumflex (*), the input field is all characters until the first char- 
acter not in the set between the brackets. If the first character after 
the left bracket is ~, the input field is all characters until the first char- 
acter which is in the remaining set of characters between the brackets. 
Ranges of the form “‘a-z’’ are allowed in the bracketed set. The spe- 
cial characters * and J] can be included in the set by making them the 
first characters in it. The corresponding argument should be a char- 
acter pointer, pointing to a character array large enough to accept 
both the string and a terminating NULL, which will be added. 


elf[g|E|FIG 
- A floating-point number is expected; the corresponding argument 


should be a pointer to a float, or double if there is a preceding 1. 


White-space characters in the string to be decoded are ignored, except 
insofar as they serve to delimit substrings to be decoded. Conversion 
proceeds until either it completes or something cannot be decoded accord- 
ing to the format specification. Arguments for which a value cannot be . 
decoded are left unchanged. | 


RETURNS . 
The number of arguments to which values have been successfully assigned. 


SEE ALSO | 
fioLib, ANSI specification for scanf( ) conversions 
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NAME 
fioRead( ) - read a buffer 
SYNOPSIS 
int fioRead (fd, buffer, maxbytes) 


int fd; /* £ile descriptor of file to read */ 
char ‘buffer; /* buffer to receive input */ 
int maxbytes; /* maximum number of bytes to read */ 


DESCRIPTION 
This routine repeatedly calls the routine read() until maxbytes have been 
read into buffer. If EOF is reached, the number of bytes read will be less than 
maxbytes. | 


NOTE 

In previous versions of Vx960 (4.0.2 and earlier), read() did not always 
return as many bytes as the user specified, even if there were sufficient bytes 
remaining in a file. Thus fioRead() was often used to make sure that a com- 
plete buffer was read. As of 5.0, the definition of read{ ) has been changed to 
be POSIX compliant, such that a complete buffer will be returned if there are 
sufficient bytes remaining in a file system fd. Some uses of fioRead() may 
therefore be unnecessary. However, fioRead() may still be useful for read- 
ing from non-file-system fds, such as serial channels or network sockets, 
where read() may still return with a partially filled buffer. 


RETURNS 
The number of bytes read, or ERROR if there is an error during the read 
operation. 


SEE ALSO 
fioLib, read{} 


NAME 

fioRdString( ) - read a string from a file 
SYNOPSIS 

int fioRdString (fd, string, maxbytes) 


int fd; /« £ile descriptor of device to read */ 
char string{]; /* buffer to receive input */ 
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int maxbytes; /* maximum number of characters to read */ 


DESCRIPTION 
This routine puts a line of input into string. The specified input fd is read 
until maxbytes, an EOF, an EOS, or a newline character is reached. A newline 
character or EOF is replaced with EOS, unless maxbytes characters have been 
read. 


RETURNS | 
The length of the string read, including the terminating EOS or EOF. 


SEE ALSO 
fioLib 
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NAME 
floatLib - floating-point formatting and scanning library 


SYNOPSIS 
floatInit( ) - initialize floating-point I/O support 


VOID floatInit () 


DESCRIPTION 
This library provides the floating-point I/O formatting and scanning sup- 
port routines. 


The floating-point formatting and scanning support routines are not directly 
callable but rather get connected to call-outs in the printf() and scanf( ) fam- 
ily of functions in fioLib. This is done dynamically by the routine 
floatInit( ) (called in  wusrRoot() in  usrConfig.c) if the 
INCLUDE FLOATING POINT option is defined in configAILh. If this 
option is omitted (i.e., floatInit() is not called), floating-point format specifi- 
cations in printf() and sscanf() will not be supported. 


SEE ALSO 
fioLiv( ) 


INCLUDE FILE floatLib.h 


NAME 
floatInit( ) - initialize floating-point I/O support 


SYNOPSIS 
VOID floatInit () 


DESCRIPTION 
This routine must be called if floating-point format specifications are to be 
supported by the printf() and scanf() family of routines. If 
INCLUDE_FLOATING POINT has been defined in configAILh, it is called 
by the root task, usrRoof( ), in usrConfig.c. 


RETURNS 
N/A 
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SEE ALSO 
floatLib 
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NAME 
fppA Lib - floating-point support assembly language routines 


SYNOPSIS 
fppSave( ) - save the floating-pointing context 
 fppRestore( ) - restore the floating-point context 


VOID fppSave (pFpContext) 
VOID fppRestore (pFpContext) 


DESCRIPTION 
This library contains routines to support the 80960SB and 80960KB floating- 
point. The routines fppSave( ) and fppRestore( ) save and restore all the task 
floating-point context information. 


Higher-level access mechanisms are found in fppLib. 


SEE ALSO 
fppLib 
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NAME 


fppLib - floating-point support library 


SYNOPSIS 
fopTaskRegsShow( ) - display the floating-point registers of a task 
fppTaskRegsGet{ ) - get the floating-point registers from a task TCB 
fppTaskRegsSet( ) - set the floating-point registers of a task 
fppProbe( ) - probe for the presence of a floating-point support 


VOID fppInit () 

VOID fppTaskRegsShow (task) 

STATUS fppTaskRegsGet (task, fpregs, pFpcr, pFpsr, pFpiar) 
STATUS fppTaskRegsSet (task, fpregs, fpcr, fpsr, fpiar) 
STATUS fppProbe () 


DESCRIPTION 
This library provides a low-level interface to the floating point for 80960KB 
and 80960SB. The routines fppTaskRegsShow(), fppTaskRegsSet{ ), and 
fppTaskRegsGet() inspect and set floating point registers on a per task 
basis. The routine fppProbe() checks for the presence of the 80960KB or 
80960SB. With the exception of fppProbe(), the higher level facilities in 
dbgLib and usrLib should be used instead of these routines. 


VX_FP_TASK OPTION 
Saving and restoring floating-point registers adds to the context switch time 
of a task. Therefore, floating-point registers are not saved and restored for 
every task. Only those tasks spawned with the task option VX_FP_TASK 
will have floating-point registers saved and restored. 


NOTE: If a task does any floating-point operations, it must be spawned 
with VX_FP_TASK. 


INTERRUPT LEVEL | 
Floating-point registers are not saved and restored for interrupt service rou- 
tines connected with intConnect( ). However, if necessary, an interrupt ser- 
vice routine can save and restore floating-point registers by calling routines 
in fppALib. See the manual entry for intConnect( ) for more information. 


SEE ALSO 
fppALib, intConnect() 
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NAME 
fppTaskRegsShow/( ) - display the floating-point registers of a task 


SYNOPSIS 
VOID fppTaskRegsShow (task) 
int task; /* task to print registers for */ 


DESCRIPTION 
This routine displays the contents of the floating-point registers for task in 
the following format: 


fpO0 =... 
fpl =... 
fp2 = 2. 
fp3 = ... 


If the floating-point registers are not supported, nothing is printed. 


RETURNS 
N/A 


SEE ALSO 
fppLib 


NAME 
fppTaskRegsGet, ) - get the floating-point registers from a task TCB 


SYNOPSIS 
STATUS fppTaskRegsGet (task) 
int task; /* task to get info about «/ 
fppTaskRegsGet (task, pRegs) 
REG SET *pRegs 


DESCRIPTION 


This routine copies the floating-point registers of a task into the REG SET 
structure. The floating-point registers are copied in an array containing four 
80-bit registers. : 
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NOTE 
This routine only works well if task is not the calling task. If a task tries to 
discover its own registers, the values will be stale (i.e., leftover from the last 
task switch). 


RETURNS a 
OK, or ERROR if there is no floating-point support 


SEE ALSO 
fppLib, fppTaskRegsSet( ) 
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NAME | 
fppTaskRegsSet( ) - set the floating-point registers of a task 


SYNOPSIS 
STATUS fppTaskRegsSet (task, pRegs) 


REG SET *“pRegs} 


DESCRIPTION 
This routine loads the specified values into the specified task TCB. The four 
80-bit registers are copied. 


RETURNS 
OK, or ERROR if there is no floating-point support 


SEE ALSO : 
fppLib, fppTaskRegsGet{ ) 
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NAME 
fppProbe( ) - probe for the presence of floating-point support 


SYNOPSIS 
STATUS fppProbe () 


DESCRIPTION 
This routine reports which library the current code has linked with. 
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IMPLEMENTATION 
When the Vx960 kernel is built, it is linked with appropriate libraries for the 
target processor. This routine reports whether the library had the ability to 
use hardware floating point. Software floating point can always be used. 


The probe is only performed the first time this routine is called. The result is 
stored in a static and returned on subsequent calls without actually probing. 


RETURNS 
OK if the floating-point support is present, otherwise ERROR. 


SEE ALSO 
fppLib 


Rev: 29 Aug 91 : Intel T- 97 


Vx960 5.0 - Reference Manual §.0 - oyferense Menudo oe OS ue 


NAME 


ftpLib - ARPA File Transfer Protocol Hptany: 


SYNOPSIS 
ftpCommand() - ead an FTP command and get the reply 
ftpXfer() - initiate a transfer via FTP 
ftpReplyGet() - get an FTP command reply 
ftpHookup( ) - get a control connection to the FTP server on a specified host 
ftpLogin( ) - log in to a remote FTP server 
ftpDataConntInit( ) - initialize an FTP data connection 
ftpDataConnGet{ ) - get a completed FTP data connection 


int ftpCommand (ctrlSock, fmt, argl, arg2, arg3, arg4, arg5S, arg6) 
STATUS ftpXfer (host, user, passwd, acct, and, dirname, filename, ... 
int ftpReplyGet (ctrlSock, expecteof) 

int ftpHookup (host) 

STATUS ftpLogin (ctrlSock, user, passwd, account) 

int ftpDataConnInit (ctrlSock) 

int ftpDataConnGet (dataSock) 


DESCRIPTION 
This library provides facilities for transferring files to and from a host via 


File Transfer Protocol (FTP). This ah implements only the “‘client’’ side 
of the FTP facilities. 


FTP IN VXWORKS 
Vx960 provides an I/O driver, netDrv, that allows transparent access to 
remote files via standard I/O system calls. The FTP facilities of ftpLib are 
primarily used by netDrv to access remote files. Thus for most purposes, 
familiarity with ftpLib is not necessary. 


HIGH-LEVEL INTERFACE | 
The routines ftpXfer( ) and ftpReplyGet( ) provide the highest level of direct 
interface to FIP. The routine ftpXfer() connects to a specified remote FTP 
server, logs in under a specified user name, and initiates a specified data 
transfer command. The routine ftpReplyGet() receives control reply mes- 
sages sent by the remote FTP server in response to the commands sent. 


LOW-LEVEL INTERFACE 
The routines ftpHookup(), _ ftpLogin(), ftpDataConnInit{ ), 
ftpDataConnGet( ), and ftpCommand() provide the primitives necessary to 
create and use control and data connections to remote FTP servers. The fol- 
lowing example shows how to use these low-level routines. It implements 
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roughly the same function as ftpXfer{ ). 
char “host, “user, *passwi, *acct, *dirname, *filename:; 
int ctrlSock = ERROR; 
int dataSock = ERROR; 


4f (((ctrlSock = ftpHookup (host)) == ERROR) [| 
(ftpLogin (ctrlSock, user, passwd, acct) == ERROR) {| 
(ftpCommand (ctrlSock, “TYPE I") I= FTP_COMPLETE) | 
(ftpCommand (ctrlSock, “CWD ts", dizname) != FIF COMPLETE) | | 
((dataSock = ftpDataConnInit (ctrlSock)) == ERROR) {| 
(ftpCommand (ctrlSock, “RETR ts", filename) != FTP_PRELIM) || 
((dataSock = ftpDataConnGet (dataSock)) == ERROR)) 
‘ | 


/* an error occurred; close any open sockets and return * 


1£ (ctrlSock != ERROR) 

close (ctrlSock) ; 

if (dataSock |= ERROR) 

close (dataSock); 
return (ERROR) } 


} 
INCLUDE FILE 
ftpLib.h 


SEE ALSO 
netDrv 


NAME 
ftpCommand() - send an FTP command and get the reply 


SYNOPSIS 
int ftpCommand (ctrlSock, fmt, argl, arg2, arg3, argi, arg5, arg6) 
int ctrlSock; /* fd of control connection socket */ 


char *fmt; /* format string of command to send */ 
int argl; /* arguments to format string */ 

int arg2; 

int arg3; 

int arg4; 

int arg5; 

int arg6; 
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DESCRIPTION 
This routine sends the specified command on the specified socket, which 
should be a control connection to a remote FTP server. The command is 
specified as a string in printf( ) format with up to 6 arguments. 


After the command is sent, ftpCommand() waits for the reply from the 
remote server. The FIP reply code is returned in the same way as in 


fipReplyGet(). 


EXAMPLE | 
ftpCommand (ctrlSock, “TYPE I"); /* image-type xfer * 
ftpCommand (ctrlSock, “STOR %s", filename); /* init file write * 


RETURNS : 
1 = FTP_PRELIM (positive preliminary) 
2 = FTP_COMPLETE (positive completion) 
3 = FIP_CONTINUE (positive intermediate) 
4=FTP_TRANSIENT (transient negative completion) 
5 = FTP_ERROR (permanent negative completion) 


ERROR if read/write error or unexpected EOF. 


SEE ALSO 
ftpLib, ftpReplyGet( ) 


NAME 
ftpXfer( ) - initiate a transfer via FTP 


SYNOPSIS 
STATUS ftpXfer (host, user, passwd, acct, cmd, dirname, filename, 
pctrlSock, pDataSock) 


char ‘*host; /* name of server host */ 

char ‘user; /* user name with which to login to host */ 
char ‘*passwd; /* password with which to login to host */ 
char ‘acct; /* account with which to login to host */ 
char *cmd; /* command to send to host */ 


char *dirname; /* directory to ‘cd’ to before sending command */ 
char *filename; /* filename to send with command */ 
int *pCtrlSock; /* where to return control socket fd */ 
int *pDataSock; /* where to return data socket fd, 
* (NULL == don’t open data connection) */ 
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DESCRIPTION 3 
This routine initiates a transfer via a remote FTP server in the following 
order: 
(1) Establishes a connection to the FTP server on the specified host. 


(2) Logs in with the specified user name, password, and account, as neces- 
sary for the particular host. 


(3) Sets the transfer type to image by sending the command “TYPE I". 


(4) Changes to the specified directory by sending the command “CWD 
dirname’. 

(5) Sends the specified transfer command with the specified filename as 
an argument, and establishs a data connection. Typical transfer com- 
mands are “STOR %s”, to write to a remote file, or “RETR %s”, to read 
a remote file. 


The resulting control and data connection fds are returned via pCtrlSock and 
pDataSock, respectively. 


After calling this routine, the data can be read or written to the remote 
server by reading or writing on the fd returned in pDataSock. When all 
incoming data has been read (as indicated by an EOF when reading the data 
socket) and/or all outgoing data has been written, the data socket fd should 
be closed. The routine ftpReplyGet() should then be called to receive the 
final reply on the control socket, after which the control socket should be 
closed. 


If the FTP command does not involve data transfer (i.e., file delete or 
rename), pDataSock should be NULL, in which case no data connection will 
be established. 


EXAMPLE : 
The following code fragment reads the file “/usr/fred/myfile’ from the 
host “server”, logged in as user “fred”, with password “magic’’ and no 
account name. | 


int ctrlSock; 
int dataSock; 
char buf [512]; 
int nBytes; 


if (ftpXfer ("“server", “fred“, “magic”, "", 
“RETR ts", “/usr/fred", “myfile", 
&ctrlSock, &dataSock) == ERROR) 
return (ERROR) } 


while ((nBytes = read (dataSock, buf, sizeof (buf))) > 0) 
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close (dataSock) ; 
if (nBytes < 0) /* vead error? * 
status = ERROR); 


if (ftpReplyGet (ctrlSock) I= FIP_COMPLETE) 
status = ERROR} 


if (ftpCommand (ctrlSock, “QUIT") != FTP_COMPLETE) 
status = ERROR} 


close (ctrlSock) ; 


RETURNS 
OK, or ERROR if any socket cannot be created or if a connection cannot be 
made. 


SEE ALSO 
ftpLib, ftpReplyGet( ) 


NAME 
ftpReplyGet( ) - get an FTP command reply 


SYNOPSIS 
int ftpReplyGet (ctrlSock, expecteof) _ | 
int ctrlSock; /* control socket:-fd of Free OBNACKLORSE (eae Pe tei: 
BOOL expecteof; /* TRUE = EOF:-expected, /WALSEs-ORriscerror st] parcige eer: oh 


DESCRIPTION 
This routine gets a somuand _ on the specified iconttol socket... All the 
lines of a reply are read (multi-line replies are indicated with the continua- 
tion character “-”’ as the fourth character of all but the last line). 


The three-digit reply code from the first line is saved and interpreted. The 
left-most digit of the reply code identifies the type of code (see RETURNS 
below). 


The caller's error status is set to the complete cca reply code (see the 
manual entry for errnoGet( )). If the reply code indicates an error, the entire 
reply is printed on standard error. 
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If an EOF is encountered on the specified control socket, but no EOF was 
expected (expecteof == FALSE), then ERROR is returned. 


RETURNS 
1=FTP_PRELIM (positive preliminary) 
2 = FTP_COMPLETE (positive completion) 
3 = FTP_CONTINUE (positive intermediate) 
4=FTP TRANSIENT (transient negative completion) 
5 = FTP_ERROR (permanent negative completion) 


ERROR if there is a read/write error or an unexpected EOF. 


SEE ALSO 
ftpLib 


NAME 
ftpHookup( ) - get a control connection to the FTP server on a specified host 


SYNOPSIS 
int ftpHookup (host) 
char ‘*host; /* server host name or inet address */ 


DESCRIPTION 
_ This routine establishes a control connection to the FTP server on the speci- 
fied host. This is the first step in interacting witha remote FFP-server at-the ~. | 
lowest level. (For a higher level interaction with a remote FT P server, see 
the manual entry for ftpXfer( ).) 


RETURNS 
name is invalid, if a socket could not be created, or if a connection: couild-not 
be made. ‘ 


SEE ALSO 
ftpLib, ftpLogin( ), ftpXfer() 
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NAME | 
ftpLogin( ) - log in to a remote FTP server 


SYNOPSIS 
STATUS ftpLogin (ctrlSock, user, passwd, account) 
int ctrlSock; /* fd of control socket on which to login */ 
char ‘user; /* user name with which to login to host */ 
char ‘passwd; /* password with which to login to host */ 
char ‘account; /* account with which to login to host */ 


DESCRIPTION , 
This routine logs into a remote server with the specified user name, pass- 
word, and account name, as required by the specific remote host. This is 
typically the next step after calling ftpHookup( ) in interacting with a remote 
FTP server at the lowest level. (For a higher level interaction with a remote 
FTP server, see the manual entry for ftpXfer{( )). 


RETURNS 
OK, or ERROR if the routine is unable to log in. 


SEE ALSO 
| ftpLib, ftpHookup( ), ftpXfer( ) 


NAME , 
ftpDataConnlnit{ ) - initialize an FTP data connection 


SYNOPSIS 
int f£tpDataConnInit (ctrlSock) 
int ctrlSock; /* fd of associated control socket */ 


DESCRIPTION 
This routine sets up the client side of a data connection for the specified con- 
trol connection. It creates the data port, informs the remote FTP server of 
the data port address, and listens on that data port. The server will then 
connect to this data port in response to a subsequent data-transfer com- 
mand sent on the control connection (see the manual entry for 
ftpCommand( )). 


This routine must be called before the data-transfer command is sent; 
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otherwise, the server's connect may fail. 


This routine is called after fftpHookup({) and ftpLogin() to establish a con- 
nection with a remote FTP server at the lowest level. (For a higher level 
interaction with a remote FTP server, see ftpXfer( ).) 


RETURNS 
The fd of the data socket created, or ERROR. 


SEE ALSO 
ftpLib, ftpHookup( ), ftpLogin( ), ftpCommand( ), ftpXfer( ) 
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NAME 
ftpDataConnGet{ ) - get a completed FTP data connection 


SYNOPSIS 
int ftpDataConnGet (dataSock) 
int dataSock; /* f£d of data socket on which to await connection */ 


DESCRIPTION 
This routine completes a data connection initiated by a call to 
ftpDataConnInit{ ). It waits for a connection on the specified socket from 
the remote FTP server. The specified socket should be the one returned by 
ftpDataConnInit( ). The connection is established on a new socket, whose 
fd is returned as the result of this function. The original socket, specified in 
the argument to this routine, is closed. 


Usually this routine is called after ftpDataConnInit( ) and ftpCommand() to 
initiate a data transfer from/to the remote FTP server. 


RETURNS 
The fd of the new data socket, or ERROR if the connection failed. 


SEE ALSO , 
ftpLib, ftpDataConnInit{( ), ftpCommand( ) 
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NAME 


ftpdLib - ARPA File Transfer Protocol server 


SYNOPSIS 


ftpdTask( ) - FTP server daemon task 
ftpdlInit( ) - initialize the FTP server task 
ftpdDelete() - clean up and finalize the FTP server task 


STATUS ftpdTask () 
STATUS ftpdInit (stackSize) 
VOID ftpdDelete () 


DESCRIPTION 


This library provides File Transfer Protocol (FTP) service to allow an FIP 
client to store and retrieve files to and from the Vx960 target. The FTP is 
defined in Requests For Comments (RFC) document 959 and this library 
implements an extented subset of this specification. This implementation of 
the FTP server understands the following FTP requests: 


USER ~~ - Verify user name 
PASS — - Verify password for the user 
QUIT - Quit the session 
LIST _ - List out contents of a directory - 
NLST  - List out contents of a directory using concise format 
RETR - Retrievea file 
STOR _ - Storea file a 
CWD _ - Change Working Directory | vo. Working (isc. 
TYPE  - Change the data representation type 
PORT - Change the port number | 
PWD - Get the name of current working directory 
STRU - - Change file structure settings 


1 - 106 


MODE - Change file transfer mode 


ALLO _ - Reserver sufficient storage 
ACCT _ - Identify the user’s account 
PASV — - Make the server listen on a port for data connection 
NOOP_ - Donothing 
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The FTP server is initialized by calling ftpdInit({). This will create a new 
task, ftpdTask(). The ftpdTask() will manage multiple FTP client connec- 
tions, thus it is possible to have multiple FTP sessions running at the same 
time. For each session, a server task is spawned (ftpdWorkTask) to service the 
client. 


The FTP server is shut down by calling ftpdDelete(). This will reclaim all 
resources allocated by the FTP servers and cleanly terminate all FTP server 
processes. 


Note that this implementation supports all commands suggested by RFC- 
959 for a minimal FTP server implementation and also several additional 
commands. 


SEE ALSO 
ftpLib, netDrv, RFC-959 File Transfer Protocol 


ftpdTask( ) - FTP server daemon task 


SYNOPSIS 


STATUS ftpdTask () 


DESCRIPTION 


This routine processes incoming FTP client requests by spawning a new FTP 
work task for each connection that is set up. 


RETURNS 


© 3 
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OK, or ERROR when the task terminates with errors due to socket relatederors'< 


I/O prope lack of resources, or task creation failure. 


SEE ALSO 


ftpdLib 
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NAME 
ftpdInit( ) - initialize the FTP server task 


SYNOPSIS 
STATUS ftpdInit (stackSize) . 
int stackSize; /* stack size for the ftpdTask */ 


DESCRIPTION 
This routine will spawn a new FTP server task if one does not already exist. 
If an existing FIP server task is running already, ftpdInit() will simply 
return without creating a new task. It will simply report whether a new FTP 
task was successfully spawned. An argument stackSize can be specified to 
change the default stack size for the FTP server task. The default size is set 
in the global variable ftpdWorkTaskStackSize. 


RETURNS 
OK if a new FTP task is created successfully, ERROR otherwise. 


SEE ALSO 
ftpdLib 


NAME 
ftpdDelete( ) - clean up and finalize the FTP server task 


SYNOPSIS | 
VOID ftpdDelete () 


DESCRIPTION 
This routine finalizes and deletes the main FTP server task ftpdTask(), 
cleans up all active sessions spawned by. it, and reclaims all resources used 
by each active slot in the active session list. All sockets associated with FTP 
services will be closed, and all memory dynamically allocated will be freed. 


RETURNS 
N/A 


SEE ALSO 
ftpdLib 
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NAME 
hostLib - host table subroutine library 


SYNOPSIS | 
hostTbliInit( ) - initialize the network host table 
hostAdd( ) - adda host to the host table 
hostDelete( ) - delete a host from the host table. 
hostGetByName( ) - look up a host in the host table by its name. 
hostGetByAdadr( ) - look up a host in the host table by its Internet address 
hostShow( ) - display the host table 
sethostnamie() - set the symbolic name of this machine 
gethostname() - get the symbolic name of this machine 


VOID hostTblInit () 

STATUS hostAdd (hostName, hostAddr) 
STATUS hostDelete (name, addr) 

int hostGetByName (name) 

STATUS hostGetByAddr (addr, name) 
VOID hostShow () 

int sethostname (name, nameLen) 

int gethostname (name, nameLen) 


DESCRIPTION 
This module provides routines to store and access the network host data- 
base. The host table contains information regarding the known hosts on the 
local network. The host table (displayed with hostShow()) contains the 
Internet address, the official host name, and aliases. 


i400 


By convention, network addresses are specified in a dot (".”) notation. The 
library inetLib contains Internet address manipulation routines. Host 
names, and aliases, may contain any printable character. 


SEE ALSO 
inetLib, Programmer's Guide: Network 
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NAME 
hostTblinit( ) - initialize the network host table 


SYNOPSIS 
VOID hostTblinit () 


DESCRIPTION 
This routine initializes the host list data structure used by routines 
throughout this module. It should be called by usrRoot() in usrConfig.c, 
before any other routines in this module. 


SEE ALSO 
hostLib, usrConfig 


NAME 
hostAdd{ ) - add a host to the host table 


SYNOPSIS 
STATUS hostAdd (hostName, hostAddr) 
char ‘*hostName; /* host name. */ 
char ‘*hostAddr; /* host address in standard internet format */ 


DESCRIPTION 
This routine adds a host name to the local host table. This must be called _ 
before sockets on the remote host are opened, or before files on the remote. 
host are accessed via netDrv or nfsDryv. 


The host table has one entry per Internet address. More than one name may 
be used for an address. Additional host names are added as aliases. 


EXAMPLE 
-> hostAdd "vxhost", "90.2" 


-> hostShow 

hostname inet address aliases 
localhost 127.0.0.1 

yuba | 90.0.0.3 

vxhost 90.0.0.2 


value = 12288 = 0x3000 = bzero + 0x18 
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RETURNS 
OK, or ERROR if the host table is full, the host name is already entered, 
there is an invalid Internet address, or the routine runs out of memory. 


SEE ALSO 
hostLib, netDrv, nfsDrv 


NAME 


hostDelete( ) - delete a host from the host table. 


SYNOPSIS 
STATUS hostDelete (name, addr) 
char ‘*name; /* host name or alias */ 
char ‘addr; /* host address in standard internet format */ 


DESCRIPTION 

| This routine deletes a host name from the local host table. The host entry is 
deleted if host name is used as name. The alias of the host name is deleted if 
the alias is used as name. 


RETURNS 
OK, or ERROR if the host is unknown. 


SEE ALSO 
hostLib 
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NAME | 
hostGetByName( ) - look up a host in. the host table by its name. 


SYNOPSIS 
int hostGetByName (name) 
char ‘*name; /* name of host */ 


DESCRIPTION 
This routine returns the Internet address of a host that has been added to the 
host table by hostAdd( ). 
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RETURNS 
The Internet address (as an integer), or ERROR if the host is unknown. 


SEE ALSO 
hostLib 
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NAME : 
hostGetByAddr( ) - look up a host in the host table by its Internet address 


SYNOPSIS 
STATUS hostGetByAddr (addr, name) 
int addr; //* inet address of host */ 
char ‘name; /* buffer to hold the name */ 


DESCRIPTION 
This routine finds the host name by its Internet address and puts it in name 
which should be preallocated with (MAXHOSTNAMELEN + 1) bytes of 
memory. The buffer name is null-terminated unless insufficient space is pro- 
vided. 


RETURNS 
OK, or ERROR if the host is unknown. 


WARNING 
The routine hostGetByAddr( ) does not look for aliases. Host names are lim- 
ited to MAXHOSTNAMELEN (from hostLib.h) characters, currently 64. 


SEE ALSO | 
hostLib, hostGetByNamre( ) 


NAME 
hostShow ) - display the host table 


SYNOPSIS 
VOID hostShow () 
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DESCRIPTION 
This routine prints a list of remote hosts along with their Internet addresses 
and aliases. 


RETURNS 
N/A 


SEE ALSO 
hostLib, hostAdd({ ) 


NAME 7 
sethostname( ) - set the symbolic name of this machine 


SYNOPSIS 
int sethostname (name, nameLen) 
char “name; /* machine name */ 
int mameLen; /* length of name */ 


DESCRIPTION 
This routine sets the target machine’s symbolic name which can be used for 
identification. 


SEE ALSO 
hostLib 


NAME 
gethostname( ) - get the symbolic name of this machine 


SYNOPSIS 
int gethostname (name, nameLen) 
char “name; 
int nameLen; 


DESCRIPTION 
This routine gets the target machine's symbolic name which can be used for 
identification. 
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SEE ALSO 
hostLib 
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NAME 
ifLib - network interface library 


SYNOPSIS 
ifAddrSet( ) - set an interface address for a network interface 
ifAddrGet( ) - get the Internet address of a network interface 
ifBroadcastSet( ) - set the broadcast address for a network interface 
ifBroadcastGet( ) - get the broadcast address for a network interface 
ifDstAddrSet( ) - define an address for the other end of a point-to-point link 
ifDstAddrGet{ ) - get the Internet address of a point-to-point peer 
ifMaskSet( ) - define a subnet for a network interface 
ifMaskGet( ) - get the subnet mask for a network interface 
ifFlagChange( ) - change the network interface flags 
ifFlagSet() - specify the flags for a network interface 
ifFlagGet( ) - get the network interface flags 
ifMetricSet() - specify a network interface hop count 
ifMetricGet( ) - get the metric for a network interface 
ifRouteDelete( ) - delete routes associated with a network interface 
ifunit() - map an interface name to an interface structure pointer 


STATUS 
STATUS 
STATUS 
STATUS 
STATUS 
STATUS 
STATUS 
STATUS 
STATUS 
STATUS 
STATUS 
STATUS 
STATUS 


ifAddrSet (interfaceName, interfaceAddress) 
ifAddrGet (interfaceName, interfaceAddress) 
ifBroadcastSet (interfaceName, broadcastAddress) 
ifBroadcastGet (interfaceName, broadcastAddress) 
ifDstAddrSet (interfaceName, dstAddress) 
ifDstAddrGet (interfaceName, dstAddress) 
ifMaskSet (interfaceName, netMask) 

ifMaskGet (interfaceName, --netMask) 

ifFlagChange (interfaceName, flags, on) 
ifFlagSet (interfaceName, flags) 

ifFlagGet (interfaceName, “flags) 

ifMetricSet (interfaceName,; metric) 

ifMetricGet (interfaceName, pMetric) 


int ifRouteDelete (ifName, unit) 
struct ifnet *ifunit (name) 


DESCRIPTION 
This library contains routines to configure the network interface parameters. 
Generally, each routine corresponds to one of the functions of the UNIX 
command ifconfig. 
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SEE ALSO | 
hostLib, Programmer's Guide: Network UNIX man ifconfig(8), Stevens section 
6.11 


NAME 
ifAddrSet() - set an interface address for a network interface 


SYNOPSIS 
STATUS ifAddrSet (interfaceName, interfaceAddress) 
char *interfaceName; /* name of interface to configure */ 
char ‘*interfaceAddress; /* Internet address to assign to interface */ 


DESCRIPTION 
This routine assigns an Internet address to a specified network interface. 
The Internet address can be a host name or a standard Internet address for- 
mat (e.g., 90.0.0.4). If a host name is specified, it should already have been 
added to the host table with hostAdd{ ). 


RETURNS | 
OK, or ERROR if the interface cannot be set. 


SEE ALSO | 
ifLib, ifAddrGet( ), ifDstAddrSet( ), ifDstAddrGet{ ) 


NAME 
ifAddrGet( ) - get the Internet address of a network interface 
SYNOPSIS 
STATUS ifAddrGet (interfaceName, interfaceAddress) 
char ‘*interfaceName; /* name of interface */ | 
char *interfaceAddress; /* buffer for Internet address */ 
DESCRIPTION 
This routine gets the Internet address of a specified network interface and 
copies it to interfaceAddress. 


1-116 Intel Rev: 29 Aug 91 


Librarles (1) ifLib 


RETURNS 
OK or ERROR. 


SEE ALSO 
ifLib, ifAddrSet( ), ifDstAddrSet( ), ifDstAddrGet{ ) 
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NAME 
ifBroadcastSet{( ) - set the broadcast address for a network interface 


SYNOPSIS 
STATUS ifBroadcastSet (interfaceName, broadcastAddress) 
char *interfaceName; /* name of interface to assign */ 
char ‘*broadcastAddress; /* broadcast address to assign to interface */ 


DESCRIPTION 
This routine assigns a broadcast address for the specified network interface. 
The broadcast address must be a string in standard Internet address format 
(e.g., 90.0.0.0). 


An interface’s default broadcast address is its Internet address with a host 
part of all ones (e.g., 90.255.255.255). This conforms to current ARPA specifi- 
cations. However, some older systems use an Internet address with a host 
part of all zeros as the broadcast address. 


NOTE 
Vx960 automatically accepts a host part of all zeros as a broadcast address, 
in addition to the default or specified broadcast address. But if Vx960 is to 
broadcast to older systems using a host part of all zeros as the broadcast 
address, this routine should be used to change the broadcast address of the 
interface. 


RETURNS 
OK or ERROR. 


SEE ALSO 
ifLib, ifBroadcastGet{ ) 
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NAME 
ifBroadcastGet( ) - get the broadcast address for a network interface 


SYNOPSIS 
STATUS ifBroadcastGet (interfaceName, broadcastAddress) 
char *interfaceName; /* name of interface */ 
char ‘*broadcastAddress; /* buffer for broadcast address */ 


DESCRIPTION 
This routine gets the broadcast address for a specified network interface. 


The broadcast address is copied to the buffer broadcastAddress. 


RETURNS 
OK or ERROR. 


SEE ALSO 
ifLib, ifBroadcastSet( ) 


NAME 


ifDstAddrSet( ) - define an address for the other end of a point-to-point link 


SYNOPSIS 
STATUS ifDstAddrSet (interfaceName, dstAddress) 
char ‘*interfaceName; /* name of interface to configure */ 
char *dstAddress; /* Internet address to assign to destination */ 


DESCRIPTION a. e 
This routine assigns the Internet address of a machine connected to the 
opposite end of a point-to-point network connection, such as a SLIP connec- 
tion. Inherently, point-to-point connection-oriented protocols such as SLIP 
require that addresses for both ends of a connection be specified. 


RETURNS 
OK or ERROR. 


SEE ALSO | 
ifLib, ifAddrSet( ), ifDstAddrGet{ ) 
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NAME 
ifDstAddrGet{ ) - get the Internet address of a point-to-point peer 


SYNOPSIS 
STATUS ifDstAddrGet (interfaceName, dstAddress) 
char ‘*interfaceName; /* name of interface */ 
char ‘*dstAddress; /* buffer for destination address */ 


DESCRIPTION 
This routine gets the Internet address of a machine connected to the oppo- 
site end of a point-to-point network connection. The Internet address is 
copied to the buffer dstAddress. 


RETURNS | 
OK or ERROR. 


SEE ALSO 
ifLib, ifDstAddrSet( ), ifAddrGet( ) 


NAME 
ifMaskSet({ ) - define a subnet for a network interface 


SYNOPSIS 
STATUS ifMaskSet (interfaceName,: netMask) ‘=: .: . 
char ‘*interfaceName; /* name of:-interface for which to set mask */ 
int netMask; /* subnet‘mask (e.g. Oxf£000000) */ 


DESCRIPTION. 
This routine allocates additional bits tothe :network portion of an Internet 
address. The network portion is specified with a mask that must contain 
ones in all positions that are to be interpreted.as the network portion. This 
includes all the bits that are normally interpreted as the network portion for 
the given class of address, plus the bits to be added. Note that all bits must 
be contiguous. 


In order to correctly interpret the address, a subnet mask should be set for 
an interface prior to setting the Internet address of the interface with the 
routine ifAddrSet( ). 
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RETURNS 
OK or ERROR. 


SEE ALSO 
ifLib, ifAddrSet( ) 
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NAME 
ifMaskGet( ) - get the subnet mask for a network interface 


SYNOPSIS 
STATUS ifMaskGet (interfaceName, netMask) 
char ‘*interfaceName; /* name of interface */ | 
int ‘*netMask; /* buffer for subnet mask */ 


DESCRIPTION 


This routine gets the subnet mask for a specified network interface. The 
subnet mask is copied to the buffer netMask. 


RETURNS 
OK or ERROR. 


SEE ALSO 
ifLib, ifAddrGet{ ), ifFlagGet( ) 


NAME | , 
ifFlagChange( ) - change the network interface flags 


SYNOPSIS | 
STATUS ifFlagChange (interfaceName, flags, on) 
char ‘*interfaceName; /* name of the network interface */ 


int flags; /* the flag to be changed */ 
BOOL on} /* TRUE=turn on, FALSE=turn off */ 
DESCRIPTION 


This routine changes the flags for the specified network interfaces. If the 
parameter on is TRUE, the specified flags are turned on; otherwise, they are 
turned off. The routines ifFlagGet() and ifFlagSet() are called to do the 
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actual work. 


RETURNS 
OK or ERROR. 


SEE ALSO 
ifLib, ifAddrSet( ), ifMaskSet( ), ifFlagSet( ), ifFlagGet() 


NAME 
ifFlagSet( ) - specify the flags for a network interface 


SYNOPSIS 
STATUS ifFlagSet (interfaceName, flags) 
char *interfaceName; /* name of the network interface */ 
int flags; /* network flags */ 


DESCRIPTION 
This routine changes the flags for a given network interface. Any combina- 
tion of the following flags can be specified: 


IFF_UP (0x1) 
IFF DEBUG (0x4) 
IFF_LOOPBACK (0x8) 
IFF_NOTRAILERS (0x20) 
IFF_PROMISC (0x100) 
IFF_ALLMULTI (0x200) 
IFF NOARP (0x80) 
NOTE 


The following flags can only be set at interface initialization time. Specify- 
ing these flags will not change any settings in the interface data structure. 


IFF_POINTOPOINT (0x10) 
IFF_NOTRAILERS (0x20) 
IFF_RUNNING (0x40) 


RETURNS 
OK or ERROR. 


SEE ALSO 
ifLib, ifFlagChange( ), ifFlagGet( ) 
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NAME | 
ifFlagGet( ) - get the network interface flags 


SYNOPSIS 
STATUS ifFlagGet (interfaceName, flags) 
char ‘*interfaceName; /* name of the network interface */ 
int ‘flags; — /* network flags returned here */ 


DESCRIPTION 
This routine gets the flags for a specified network interface. The flags are 
copied to the buffer flags. 


RETURNS 
OK or ERROR. 


SEE ALSO 
ifLib, ifFlagSet( ) 


oe 


NAME 
ifMetricSet( ) - specify a network interface hop count 


SYNOPSIS | 
STATUS ifMetricSet (interfaceName, metric) 
char ‘*interfaceName; /* name of the network interface */ 
int metric; ‘ {* metric for this interface */ 


DESCRIPTION Bie 

This routine configures ‘metric for a network interface from the host machine 
to the destination network. This information is used primarily by the IP 
routing algorithm to compute the relative distance for a collection of hosts 
connected to each interface.: For example, a higher metric for SLIP interfaces 
can be specified to discourage routing a packet to slower serial line connec- 
tions. Note that when metric is zero, the IP routing algorithm will allow 
directly sending a packet whose IP network address is not necessarily the 
same as the local network address. 


RETURNS 
OK or ERROR. 
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SEE ALSO 
ifLib, ifMetricGet( ) 


NAME 
ifMetricGet( ) - get the metric for a network interface 


SYNOPSIS 
STATUS ifMetricGet (interfaceName, pMetric) 
char *interfaceName; /* name of the network interface */ 
int *pMetric; /* returned interface’s metric */ 


DESCRIPTION | 
This routine retrieves the metric for a specified network interface. The 


metric is copied to the buffer pMetric. 


RETURNS 
OK or ERROR. 


SEE ALSO 
ifLib, ifMetricSet( ) 


NAME ae. Ns 
ifRouteDelete( ) - delete routés assdééiated with a network interface = + 


SYNOPSIS - rs aa 
int ifRouteDelete (ifName, unit)-"'" 
char ‘*ifName; /* name of the interface */ 


wes 
‘ 


int unit; /* unit number for this interface */ 
DESCRIPTION 
This routine deletes all routes that are associated with the specified inter- 
face. 


RETURNS | 
The number of routes deleted, or ERROR if an interface is not specified. 
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SEE ALSO 
—ifLib 


NAME 
ifunit( ) - map an interface name to an interface structure pointer 


SYNOPSIS 
struct ifnet *ifunit (name) 
char “name; 


DESCRIPTION 
This routine returns a pointer to a network interface structure for name or 


NULL if no such interface exists. For example: 


struct ifnet “pIf; 


pIlf = ifunit ("eid"); 
pif points to the data structure that describes the first network interface dev- 
ice if InO is mapped successfully. 


RETURNS 
A pointer to the interface structure, or NULL if an interface is not found. 


INCLUDE 
etherLib.h 


SEE ALSO 
ifLib, etherLib 
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NAME 
if_ bp - Vx960 & SunOS backplane driver 


SYNOPSIS 
bpattach( ) - attach the bp interface to the network 
bpInit( ) - initialize the backplane anchor 
byShow( ) - show information about the backplane network 


STATUS bpattach (unit, pAnchor, procNum, intType, intArgl, intArg2, intArg3) 
STATUS bpInit (pAnchor, pMem, memSize, tas0OK) 
VOID bpShow (bpName, zero) 


DESCRIPTION 

This module implements the Vx960 backplane aeiwor: driver. The back- 
plane driver allows several CPUs to communicate via shared memory. Usu- 
ally, the first CPU to boot in a card cage is considered the backplane master. 
This CPU has either dual-ported memory or an additional memory board 
which all other CPUs can access. Each CPU must have some way to be 
interrupted by another CPU and to be able interrupt all other CPUs. There 
are three interrupt types: polling, mailboxes, VMEbus interrupts. Polling is 
used when there are no hardware interrupts; each CPU spawns a polling 
task to manage transfers. Mailbox interrupts are the preferred method 
because they do not require an interrupt level. Using VMEbus interrupts is 
much better than polling but may require hardware jumpers. 


There are three user-callable routines: bpInit(), bpattach(), and bpShow(). 
The backplane master, usually processor 0, must initialize the backplane 
memory and structures by first calling bpInit(). Once the backplane has 
been initialized, all processors can be attached via bpattach(). Usually, 
bpInit() and bpattach() are called automatically in oe when back- 
plane parameters are specified in the boot line. 


The bpShow() routine is provided as a diagnostic aid to show all the CPUs 
configured on a backplane. 


MEMORY LAYOUT 
The following diagram shows the memory layout of a backplane network. 
All pointers in shared memory are relative to the start of shared memory, 
since dual-ported memory may appear in different places for different 
CPUs. 
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ready value | 1234567 
{ heartbeat i increments 1/sec 
| pointer to bp header | 
| watchdog | for backplane master CPU 


the backplane header may be contiguous or 
allocated elsewhere on the master CPU 


amma ewewennwen== backplane header 

| backplane header { 1234567 

; num CPUs | unused 

| ethernet address i (6 bytes) 

| pointer to free ring | 

[oneeianeielenmebinennate | 

| --------+------------------- | cpu descriptor 

| active | true/false 

| processor number i O-NCPU 

| unit | 0-NBP 

| pointer to input ring | 

| interrupt type i POLL | MAILBOX | Bus 
| interrupt argl | none | addr space | level 
interrupt arg2 ; none | address | vector 
| interrupt arg3 i none | value | none 
puiaceeomiasmanonnielin | 

| eae repeated MAXCPU times 
Loriehichectisesnaeiaosieie 

{ free ring | contains pointers to buffer nodes 
| ----------—---------------- | | 

| input ring 1 | contains pointers to buffer nodes 
[eaepiesieneacaeeeiesited | 

esate iiashacpetiial 

| input ring n ‘| ae 

| -------------------------- |= - - 

| -------------------------4| buffer node 1 

| address, length “| 

[econ neceasaeteotitens = 

| data buffer 1 

iaeeeescebisheioneiinninee | 

| -------------------------- | buffer node m 

| address, length | 

Fipmickanneainmnanlaniaee | 

| data buffer m | 

ow core oe ants ea am ee a eee een an were cm am en om me a high address 
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SEE ALSO 
Programmer's Guide: Network 


NAME 


bpattach( ) - attach the bp interface to the network 


SYNOPSIS 
STATUS bpattach (unit, pAnchor, procNun, intType, intArgl, intArg2, intArg3) 
int unit; /* backplane unit number */ 
char ‘*pAnchor; /* bus pointer to bp anchor */ 
int procNum; (/* processor number in backplane */ 
int dintType; /* interrupt type: poll, bus, mailbox */ 
int dintArgl; /* as per interrupt type */ 
int intArg2; /* as per interrupt type */ 
int intArg3; /* as per interrupt type */ 


DESCRIPTION 
This routine makes the bp interface available by filling in the network inter- 
face record. The system will initialize the interface when it is ready to accept 
packets. 


RETURN 
~ OK or ERROR. 


SEE ALSO 
if bp 
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NAME - 
| bplnit( )- initialize the backplane anchor 


SYNOPSIS 
STATUS bpInit (pAnchor, pMem, memSize, tasOK) 
char *pAnchor; /* backplane anchor address */ 


char ‘“pMam; /* start of backplane shared memory, NONE~alloc */ 
int memSize; /* num bytes in bp shared memory, 0=0x100000 */ 
BOOL tasOK; +*‘/* TRUE = hardware can do test-and-set */ 
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DESCRIPTION | 7 
This routine initializes the backplane anchor. Typically, the pAnchor and 
pMem parameters both point to the same block of shared memory. If the 
first processor is dual-porting its memory, then, by convention, the anchor is 
at 0x600 (only 16 bytes are required) and the start of memory pMem is 
dynamically allocated by using the value NONE (-1). Memory size ranges 
from a minimum of 64K to a comfortable 512K, although this may be larger. 
The tasOK parameter is provided for CPUs (e.g., Sun-3) that do not support 
the test-and-set instruction. If any test-and-set deficient CPUs are in the sys- 
tem, then all CPUs must use the software “test-and-set’’. 


RETURNS 
OK, or ERROR if data structures cannot be set up, or memory is insufficient. 


SEE ALSO 
if bp 


NAME 
bpShow( ) - show information about the backplane network 


SYNOPSIS 
VOID bpShow (bpName, xero) 
char *bpName; /* backplane interface name (NULL == “bp0") */ 
BOOL sero; /* TRUE = zap totals */ 


DESCRIPTION 
This routine shows information about the different CPUs configured in the 
backplane network. It also prints error statistics (and zeros). 


-> bpShow 
Anchor at 0x800000 
heartbeat = 705, header at 0x800010, free pkts = 237. 


cpu int type argl arg2 arg3 queued pkts rd index 
0 poll 0x0 0x0 0x0 0 27 
1 poll 0x0 0x0 0x0 Le) 11 
2 bus-int Ox3 Oxc9 Ox0 ts) 9 
3 mbox-2 Ox2d 0x8000 0x0 ¢) 1 
input packets = 192 output packets = 164 
output errors = 0 collisions = 0 
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value = 1 = Oxl 


RETURNS 
N/A 


SEE ALSO 
if bp 
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NAME 
if_enp - CMC ENP 10/L Ethernet interface driver 


SYNOPSIS 
enpattach( ) - attach the enp interface to the network 


STATUS enpattach (unit, addr, ivec, ilevel) 


DESCRIPTION 
This module implements the CMC ENP 10/L network interface driver. 


There is one user-callable routine, enpattach{ ). 


SOLEIL RAL LL LILI LLOA ALA LS CORLL LEI: 
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NAME 
enpattach( ) - attach the enp interface to the network 


SYNOPSIS 
STATUS enpattach (unit, addr, ivec, ilevel) 
int unit; /* unit number */ 
char ‘addr; /* address of enp’s shared memory */ 
int ivec; /* interrupt vector to connect to */ 
int ilevel; /* interrupt level */ 


DESCRIPTION 
This routine attaches an enp interface to the. network if the device exists. The 


system will initialize the interface wheittiitiisweadyrta-accept, packets: 2. ; is 


RETURNS d 
OK or ERROR. a 


SEE ALSO 
if_enp, ifLib, netShow 


1 - 130 Intel Rev: 29 Aug 91 


.* 
‘. 
ag . é 
oF we 


ae oe * 
t “om 


° 
Og, Ht Se 


OT brands) dE exe. 8 


NAME 
if_ex - Excelan EXOS 201/202/302 Ethernet interface driver 


SYNOPSIS 
exattach( ) - attach the ex interface to the network 


STATUS exattach (unit, devAdrs, ivac, ilevel) 


DESCRIPTION 
This module implements the Excelan EXOS 201/202/302 Ethernet interface 
driver. There is one user-callable routine, exattach( ). 


NAME 
exattach( ) - attach the ex interface to the network 
SYNOPSIS 
STATUS exattach (unit, devAdrs, ivec, ilevel) 
int unit; /* logical number of this interface */ 
char ‘*daevAdrs; /* bus address */ 
int ivec; /* interrupt vector */ 
int ilevel; /* interrupt level */ 
DESCRIPTION : 


This routine attaches an ex Ethernet interface to the network: if the:interface..: ‘-- 
exists. The routine makes the interface ‘available by filling incthetaétworwailabie: 
interface record. The system will initialize the-interfaceywhen itlis veadyto tne int: 
accept packets. «i | | 


RETURNS 
OK or ERROR. 


SEE ALSO 
if ex, ifLib, netShow 
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NAME | 
if_ In - LANCE Ethernet interface driver 


SYNOPSIS 7 
Inattach( ) - attach the Jn interface to the network | 


STATUS lnattach (unit, devAdrs, ivec, ilevel, memAdrs, memSize, meniidth, ... 


DESCRIPTION | 
This module implements the LANCE Ethernet interface driver. There is one 
user-callable routine, Inattach( ). 


PSA POOR MSI CLIO: 


NAME | 
Inattach( ) - attach the /n interface to the network 


SYNOPSIS 
STATUS lnattach (unit, devAdrs, ivec, ilevel, memAdrs, memSize, meniwidth, 
usePadding, bufSize) 


int unit; /* unit number */ 

char ‘*devAdrs; /* LANCE i/o address */ 

int ivec; /* interrupt vector */ 

int ilevel; /* interrupt level */ 

char ‘*memAdrs; /* address of memory pool (-1 == malloc it) */ 

ULONG memSize; /* only used if memory pool is NOT malloced */ 

int memWidth; /* byte-width of data (-1 = any width) «/ 

BOOL #usePadding; /* use padding when accessing RAP? */ 

int bufSize; $$ /* size of a buffer in the LANCE ring */ 
DESCRIPTION : 


This routine attaches an Jn Ethernet interface to the network if the interface 
exists. The routine makes the interface available by filling in the network 
interface record. The system will initialize the interface when it is ready to 
accept packets. 


The memAdrs parameter specifies the location of the interface memory pool; 
if NONE, the memory pool will be malloc’ed. 


The memWidth parameter sets the memory pool's data port width (in bytes); 
if NONE, any data width will be used. The bufSize parameter specifies the 
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size of a buffer in the LANCE ring; if zero, the default value of LN_BUFSIZE 
is used. If memWidth is NONE and bufSize is LN_BUFSIZE, the driver may 
attempt to loan out buffers for increased network performance. 


The usePadding parameter should be set to TRUE if the board maps RAP on 
a 4-byte instead of a 2-byte boundary (e.g., the Tadpole TP32V). 


RETURNS 
OK or ERROR. 


BUGS 
To zero out LANCE data structures, this routine uses bzero( ), which ignores 
the memWidth specification and may use any size data access to write to 
memory. 


SEE ALSO 
if In, ifLib 
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NAME 
if _sl - serial line IP (SLIP) network interface driver 


SYNOPSIS 
slipInit( ) - initialize the SLIP interface 
slipBaudSet() - set the baud rate for a SLIP interface 
slattach() - attach a SLIP interface to the network 
slipDelete() - delete a SLIP interface 


STATUS slipInit (unit, devName, myAddr, peerAddr, baud) 
STATUS slipBaudSet (unit, baud) 

STATUS slattach (unit, fd) 

STATUS slipDelete (unit) 


DESCRIPTION 
This module implements the Vx960 Serial Line IP (SLIP) network driver. 
The SLIP driver allows Vx960 to talk to other machines over serial connec- 
tions by encapsulating IP packets into streams of bytes suitable for serial 
transmission. 


USER-CALLABLE ROUTINES 
SLIP devices are initialized using slipInit(), specifying the Internet address 
for both sides of the SLIP point-to-point link and the name of the tty device 
on the local host. It calls slattach() to attach the SLIP interface to the net- 
work. The slipDelete() routine deletes a specified SLIP interface. | 


LINK-LEVEL PROTOCOL 
SLIP is a simple protocol that uses four token characters to delimit each 
packet: 


- END (0300) 

- ESC (0333) 

- TRANS _END (0334) 
- TRANS ESC (0335) 


END is used to denote the end of an IP packet. The ESC (not to be confused 
with ASCII ESC) is used to circumvent potential occurrences of the END 
character within a packet as well as the ESC character itself. When an END 
character is to be embedded within a packet, SLIP will send a sequence of 
“ESC TRANS _END” instead, to avoid confusion between a SLIP-specific 
END and actual data whose value is the END character. To send ESC char- 
acter itself, “ESC TRANS ESC” is used. 


On the receiving side of the connection, SLIP uses the opposite actions to 
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decode the SLIP packets. Whenever END character is received, SLIP will 
assume a full IP packet has been received and send it up to the IP layer. 


IMPLEMENTATION 
The write side of a SLIP connection is an independent task. Each SLIP inter- 
face will have its own output task that will send SLIP packets over a particu- 
lar tty device channel. Whenever a packet is ready to be sent out, the SLIP 
driver will activate this task by giving a semaphore. When the semaphore is 
available, the output task will perform packetization (as explained above) 
‘and write the packet to the tty device. 


The receiving side is implemented as a “‘hook’ into the tty driver. A tty 
ioctl( ) request FIOPROTOHOOK informs the tty driver to call the SLIP 
interrupt routine every time a character is received from a serial port. By 
tracking the number of characters and watching for the END character, the 
number of calls to read() and context switching time have been reduced. 
The SLIP interrupt routine will queue a call to the SLIP read routine only 
when it knows that a packet is ready in the tty driver's ring buffer. The SLIP 
read routine will read a whole SLIP packet at a time and process it according 
to the SLIP framing rules. When a full IP packet is decoded out of SLIP 
packet, it is queued to IP’s input queue. | 


SEE ALSO 
tyLib, John Romkey: RFC-1055, entitled A Nonstandard for Transmission of IP 
Datagrams Over Serial Lines: SLIP 


ACKNOWLEDGEMENT 
This program is based on the original work done by Rick Adams of Center 
for Seismic Studies and Chris Torek of University of Maryland. 


NAME 


slipInit() - initialize the SLIP interface 


SYNOPSIS 

STATUS slipInit (unit, devName, myAddr, peerAddr, baud) 
int unit; /* SLIP device unit number (0 = HSLIP-1) */ 
char *devName; /* name of the tty device to be initialized */ 
char ‘*myAddr; /* address of the SLIP interface */ 
char ‘*peerAddr; /* address of the remote peer SLIP interface */ 
int baud; /* baud rate for this SLIP device */ 

/* 0 = don’t set baud rate */ 
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DESCRIPTION 
This routine initializes a SLIP device. Its parameters specify the name of the 
tty device and the Internet addresses of both sides of the SLIP point-to-point 
link, i.e., the local and remote sides of the serial line connection. 


The Internet address of the local side of the connection is specified in 
myAddr and the name of its tty device is specified in deuName. The Internet 
address of the remote side is specified in peerAddr. If baud is not zero, the 
baud rate will be the specified value; otherwise, the default baud rate will be 
the rate set by the tty driver. The unit parameter specifies the SLIP device 
unit number. Up to NSLIP (20) units may be created. 


For example, the following call initializes a SLIP device, using the console’s 
second port, where the Internet address of the local host is 192.10.1.1 and a 
the address of the remote host is 192.10.1.2. The baud rate will be the default 


rate for /tyCo/1. 
slipInit (0, "/tyCo/1", "192.10.1.1", "192.10.1.2", 0); 


RETURNS 
OK, or ERROR if the device cannot be opened, memory is insufficient, or the 


route is invalid. 


SEE ALSO 
if_sl 
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NAME 
slipBaudSet( ) - set the baud rate for a SLIP interface 


SYNOPSIS 
STATUS slipBaudSet (unit, baud) 
int unit; /* SLIP device unit number */ 
int baud; /* baud rate */ 


DESCRIPTION 
This routine adjusts the baud rate of a tty device attached to a SLIP interface. 
It provides a way to modify the baud rate of a tty device being used as a 
SLIP interface. 


RETURNS 
OK, or ERROR if the unit number is invalid or not initialized. 
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SEE ALSO 
if sl 


NAME 
slattach( ) - attach a SLIP interface to the network 


SYNOPSIS 
STATUS slattach (unit, fd) 
int unit; /* SLIP device unit number */ 
int fd; /* file descriptor of tty device for SLIP interface */ 


DESCRIPTION 
This routine attaches an s/ Ethernet interface to the network. It is usually 
called by slipInit(). It inserts a pointer to the SLIP interface data structure 
into a linked list of available network interfaces. 


RETURNS 
OK or ERROR. 


SEE ALSO 
| if_sl 


NAME 
slipDelete( ) - delete a SLIP interface 


SYNOPSIS 
STATUS slipDelete (unit) 
int unit; /« SLIP unit number */ 


DESCRIPTION 
This routine resets a specified SLIP interface. It detaches the tty from the sl 
unit and deletes the specified SLIP interface from the list of network inter- 
faces. For example, the following call will delete the first SLIP interface from 
the list of network interfaces: 


slipDelete (0); 
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RETURNS 
OK, or ERROR if the unit number is invalid or uninitialized. 


SEE ALSO 
if_sl 
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NAME 


inetLib - Internet address manipulation routines 


SYNOPSIS 
inet_addr() - convert a dot notation Internet address to a long integer 
inet_Inaof() - get the local address (host number) from the Internet address 
inet_makeaddr_b() - form an Internet address from the network and host numbers 
inet_makeaddr() - form an Internet address from the network and host numbers 
inet_netof() - return the network number from an Internet address 
inet_netof_string() - extract the network address in dot notation 
inet_network( ) - convert an Internet network number from a string to an address 
inet_ntoa_b() - convert network dot notation address to ASCII 
inet_ntoa() - convert network dot notation address to ASCII 


u_long inet_addr (inetString) 

int inet _Inaof (inetAddress) 

VOID inet_makeaddr_b (netAddr, hostAddr, pInetAddr) 
struct in addr inet_makeaddr (netAddr, hostAddr) 
int inet_netof (inetAddress) 

VOID inet_netof_string (inetString, netString) 
u_long inet_network (inetString) 

VOID inet _ntoa_b (inetAddress, pString) 

char *inet_ntoa (inetAddress) 


DESCRIPTION 
The library inetLib provides routines for manipulating Internet addresses, 
including the UNIX BSD 4.3 “inet_”’ routines. It includes routines for con- 
verting between character.addresses in Internet standard dot notation and 
integer addresses, routines ‘for-extracting the nétwork and host portions out 
of an Internet address, and-routines for constructing Internet addresses 
given the network and host.address parts. 


All Internet addresses are returned in network order (bytes ordered from left 
to right). All network numbers and local address parts are returned as 
machine format integer values. 


INTERNET ADDRESSES 
Internet addresses are typically specified in dot notation or as a 4-byte 
number. Values specified using the dot notation take one of the following 
forms: 


a.b.c.d 
a.b.c 
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a.b 
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When four parts are specified, each is interpreted as a byte of data and 
assigned, from left to right, to the four bytes of an Internet address. Note 
that when an Internet address is viewed as a 32-bit integer quantity on any 
i960 family machine, the bytes referred to above appear as “‘a.b.c.d” are 
ordered from right to left. 


When a three-part address is specified, the last part is interpreted as a 16-bit 
quantity and placed in the right-most two bytes of the network address. 
This makes the three-part address format convenient for specifying Class B 
network addresses as “128.net.host’”’. 


When a two-part address is supplied, the last part is interpreted as a 24-bit 
quantity and placed in the right-most three bytes of the network address. 
This makes the two-part address format convenient for specifying Class A 
network addresses as “‘net.host’”’. 


When only one part is given, the value is stored directly in the network 
address without any byte rearrangement. 


All numbers supplied as parts in a dot notation may be decimal, octal, or 
hexadecimal, as specified in the C language. That is, a leading Ox or 0X 
implies hexadecimal; otherwise, a leading 0 implies octal. With no leading 0, 
the number is interpreted as decimal. 


INCLUDE FILES 


inetLib.h, in.h 


SEE ALSO 


UNIX BSD 4.3 documentation for inet(3N), Programmer's Guide: Network 
Stevens, Section 6.5 


NAME 


inet_addr( ) - convert a dot notation Internet address to a long integer 


SYNOPSIS 


u_long inet addr (inetString) 
char *inetString; 
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DESCRIPTION | 
This routine interprets an Internet address. All the network library routines 
call this routine to interpret entries in the data bases which are expected to 
be an address. The value returned is in network order. 


EXAMPLE 
inet_addr ("90.0.0.2"); 


Returns 0x5a000002 on a big-endian machine. Returns 0x200005a on a little- 
endian machine like the i960 microprocessor. 


RETURNS 
The Internet address, or ERROR. 


SEE ALSO 
inetLib, Programmer's Guide: Network 


NAME 
inet_Inaof() - get the local address (host number) from the Internet address 


SYNOPSIS 
int inet_lnaof (inetAddress) 
int inetAddress; /* inet address from which to extract local portion */ 


DESCRIPTION | 
This routine returns the local network address portion of an Internet 
address. The routine handles class A, B, and C network number formats. 


EXAMPLE 
inet_lInaof (0x5a0000002) ; 
returns 2 on a big-endian machine. Returns O0x5a on little-endian machine 
like the i960 microprocessor.. 


RETURNS 
The local address portion of inetAddress. 


SEE ALSO 
inetLib, Programmer's Guide: Network - 
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inet_makeaddr_b() - form an Internet address from the network and host 


numbers 
SYNOPSIS 
VOID inet makeaddr_b (netAddr, hostAddr, pInetAddr) 
int netAddr; /* network part of the inet address */ 
int hostAddr; /* host part of the inet address */ 
struct in addr ‘*pInetAddr; /* where to return the inet address */ 
DESCRIPTION 


This routine constructs the Internet address from the network number and 
local host address. This routine is identical to the UNIX inet_makeaddr{ ) 
routine except that a buffer for the resulting value must provided. 


EXAMPLE 
inet _makeaddr_b (Ox5a, 2, pInetAddr) ; 


Returns the address 0x5a000002 in the location pointed to by plnetAddr ona 
big-endian machine. Returns 0x200005a on a little-endian machine like the 
i960 microprocessor. 


RETURNS 
N/A 


SEE ALSO 
inetLib, Programmer's Guide: Network 


NAME 
inet_makeaddr() - form an Internet address from the network and host 
numbers 


SYNOPSIS 
struct in addr inet _makeaddr (netAddr, hostAddr) 
int netAddr; 
int hostAddr; 
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DESCRIPTION 
This routine constructs the Internet address from the network number and 
local host address. 


WARNING | 
This routine is supplied for UNIX compatibility only. Each time this routine 
is called, four bytes are allocated from memory. Use inet_makeaddr_b() 
instead. 


EXAMPLE 
inet_makeaddr (Ox5a, 2); 
returns the address 0x5a000002 to the structure in_addr. 


RETURNS 
The network address in an in_addr structure. 


SEE ALSO 
inetLib, inet_makeaddr_b( ), Programmer's Guide: Network 


NAME 
inet_netof() - return the network number from an Internet address 


SYNOPSIS 
int inet_netof (inetAddress) 
struct in addr inetAddress; /* the inet address */ 


DESCRIPTION | 
This routine extracts the network portion ofan Internet address. 


EXAMPLE | 
inet_netof (0x5a000002); 


returns 0x5a. 


RETURNS 
The network portion of inetAddress. 


SEE ALSO 
inetLib, Programmer's Guide: Network 
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NAME 


inet_netof_string() - extract the network address in dot notation 


SYNOF'SIS 
VOID inet_netof string (inetString, netString) 
char *inetString; /* Internet address to extract local portion from */ 
char ‘*netString; /* net Internet address to return */ 


DESCRIPTION 
This routine extracts the network Internet address from a host Internet 
address (specified in dot notation). The routine handles class A, B, and C 
network addresses. The buffer netString should be INET_ADDR_LEN bytes 
long. 


NOTE | | 
This is the only routine in inetLib that handles subnet masks correctly. 


EXAMPLE 1 | 
inet_netof string ("90.0.0.2", netString) ; 


Returns “90.0.0.0°’ in netString. 


RETURNS 
N/A 


EXAMPLE 2 - for subnet mask 
hostAdd(“lshost", “143.185.6.9") 
if MaskSet("eiOd", Oxff£EL£00) 
inet _Netof_string("143.185.6.44", netString) 


RETURNS 
Returns “°143.185.6.0" in netString. 


SEE ALSO 
inetLib 
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NAME 
inet_network() - convert an Internet network number from a string to an 
address 


SYNOPSIS 
u_long inet_network (inetString) 
char *inetString; /* string version of inet addrs */ 


DESCRIPTION | 
This routine forms a network address given an ASCII Internet network 
number. 


EXAMPLE 
inet network ("90"); 


returns Ox5a. 


RETURNS 
The Internet address version of an ASCII string. 


SEE ALSO 
inetLib, Programmer's Guide: Network 


NAME 
inet_ntoa_D( ) - convert network dot notation address to ASCII 


SYNOPSIS 

| VOID inet ntoa_b (inetAddress, pString) 
struct in addr inetAddress; | 
char. *pString; /* where to return ASCII string */ 


DESCRIPTION 
This routine converts an Internet address in network format to dot notation. 


This routine is identical to the UNIX inet_ntoa() routine except that a buffer 
of size INET_ADDR_LEN must be provided. 


EXAMPLE 
inet_ntoa_b (0x200005a, pString); 
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returns the string ‘’90.0.0.2” in pString. 


RETURNS 
N/A 


SEE ALSO 
inetLib 


NAME 
inet_ntoa() - convert network dot notation address to ASCH 


SYNOPSIS 
char *inet_ntoa (inetAddress) 
struct in addr inetAddress; 


DESCRIPTION 
This routine converts an Internet address in network format to dot notation. 


WARNING 
This routine is supplied for UNIX compatibility only. Each time this routine 
is called, 18 bytes are allocated from memory. Use inet_ntoa_b() instead. 


EXAMPLE 
inet_ntoa (0x200005Sa) ; 
returns a pointer to the string “90.0.0.2””. 


RETURNS 
A pointer to the string version of an Internet address. 


SEE ALSO 
inetLib, inet_ntoa_b( ), Programmer's Guide: Network 
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NAME 
intALib - interrupt library assembly language routines 


SYNOPSIS 
 intLevelSet() - set interrupt level 


int intLevelSet (level) 


DESCRIPTION 
These routines are used to support various functions associated with inter- 
rupts from C. The routine intLevelSet (2) changes the current interrupt level 
of the processor. 


SEE ALSO 
intLib (1) 


NAME 


intLevelSet() - set interrupt level 


SYNOPSIS 
int intLevelSet (level) 
int level; /* new interrupt level mask (0-31) */ 


DESCRIPTION | 
This routine changes théinterrupt maskeir: the: status:repister-to:take on the 
value specified by level: 'Itais‘strorigly'advised that the level be in the range 
0-31. “ets | 


Setting interrupts involves.-privileged instructions, thus user-level tasks 
must trap to supervisor:level::-before executing this routine. This routine 
should only be called in supervisor mode. 


RETURNS 
previous interrupt level 0-31. 


SEE ALSO 
intALib 
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NAME 
intLib - interrupt subroutine library 


SYNOPSIS | 
intConnect( ) - connect C routine to hardware interrupt 
intHandlerCreate( ) - construct interrupt handler for C routine 
intLockLevelSet( ) - set the current interrupt lock-out level 
intLockLevelGet{ ) - get the current interrupt lock-out level 
intRestrict() - restrict interrupt context from using a routine 
intContext( ) - determine if we are in interrupt context or task context 
intCount( ) - get current interrupt nesting depth 
intLock( ) - lock out interrupts 
intUnlock( ) - cancel effect of intLock 
intVecBaseSet( ) - set the vector base address 
intVecBaseGet{ ) - get the vector base address 
intVecSet( ) - set CPU vector 
intVecGet( ) - get vector 


STATUS intConnect (vector, routine, parameter) 
FUNCPTR intHandlerCreate (routine, parameter) 
VOID intLockLevelSet (newLevel) 

int intLockLevelGet () 

STATUS intRestrict () 

BOOL intContext () 

int intCount () 

int intLock () 

int intUnlock (level) 

VOID intVecBaseSet (baseAddr) 

FUNCPTR *intVecBaseGet () 

VOID intVecSet (vector, function) 

FUNCPIR intVecGet (vector) 


DESCRIPTION 

This library provides routines to manipulate and connect to hardware inter- 
rupts and exceptions. Most importantly, any C language routine can be con- 
nected to any exception, interrupt, or trap by calling the routine intConnect. 
Interrupt vectors can be accessed directly by the routines intVecSet and 
intVecGet. The vector base register can be accessed by the routines in 
intVecBaseGet. Tasks can lock and unlock interrupts by calling the routines 
intLock and intUnlock. The routines intCount and intContext can be used 
to determine whether the CPU is running in an interrupt context or in a nor- 
mal task context. 
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INTERRUPT VECTORS AND NUMBERS 


Most of the routines in this library take an interrupt vector as a parameter, 
which is the byte offset into the vector table. Macros are provided to con- 
vert these interrupt vectors to interrupt numbers and vice versa: 
IVEC TO_INUM(intVector) changes a vector to a number. 
INUM_TO_IVEC(intNumber) turns a number into a_ vector. 
TRAPNUM_TO_IVEC(trapNumber) converts a trap number to a vector. 


EXAMPLE 


There are instances where it is desired to switch between one of several rou- 
tines for a particular interrupt. The following code fragment is one alterna- 
tive. 


vector ™= INUM_TO_IVEC(scme_int_vec_num)}; 

oldfunc = intVecGet (vector); 

newfunc = intHandlerCreate (routine, parameter) ; 
intVecSet (vector, newfunc); 

intVecSet (vector, oldfunc); /* use original routine * 


intVecSet (vector, newfunc); /* reconnect new routine * 


NAME 


intConnect( ) - connect C routine to hardware interrupt 


SYNOPSIS 


STATUS intConnect (vector, routine, parameter) | 
VOIDFUNCPTR *vector; /* interrupt vector to attach to */ 
VOIDFUNCPTR routine; /* routine to be called */ 
int parameter} /* parameter to be passed to routine */ 


DESCRIPTION 


This routine connects the specified C routine to the specified interrupt vec- 
tor. When an interrupt occurs that vectors through the specified address, 
the routine will be called with the specified parameter. The routine will be 
invoked in supervisor mode at interrupt level. A proper C environment will 
have been established, the necessary registers saved, and the stack set up. 


The routine can be any normal C code, except that it must not invoke certain 
operating system functions. 
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This routine simply calls intHandlerCreate (2) and intVecSet (2). It is the 
address of the handler returned by intHandlerCreate (2) that actually gets 
put in the interrupt vector. 


RETURNS _ 
OK or 
ERROR if unable to build interrupt handler 


SEE ALSO 
intLib, intHandlerCreate (2), int VecSet (2) 


NAME 


intHandlerCreate( ) - construct interrupt handler for C routine 


SYNOPSIS 
FUNCPTR intHandlerCreate (routine, parameter) 
FUNCPTR routine; /* routine to be called */ 
int parameter; /* parameter to be passed to routine */ 


DESCRIPTION 
This routine builds an interrupt handler around the specified C routine. 
This interrupt handler is then suitable for connecting to a specific vector 
address with intVecSet (2). The routine will be invoked in supervisor mode 
at interrupt level. A proper C environment will have been established, the 
necessary registers saved, and the stack set up. 


The routine can be any normal C code, except that it must not invoke certain 
operating system functions. 


IMPLEMENTATION | 
This routine builds an interrupt handler of the following form in allocated 
memory. 

0x90403000, Ox00000000, id _errno, x8 
0x86003000, Ox00000000, callx _intEnt 
0x5c201e01, mov 1, r4 
0x65210284, modpe r4, r4, r4 
0x5c281601, mov sp, x5 
0x8c200040, lida 0x40,xr4 
0x59084004, addo r4, 8p, sp 
Oxb2815000, stq gO, (x5) 
Oxb2al6010, stq g4,0x10(r5) 
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Oxb2c16020, stq g8,0x20(r5) 
0xa2e16030, stt g12,0x30(r5) 
Ox8c803000, Ox00000000, ida parameter, g0 
O0x5c£01e00, mov 0,g14 
0x86003000, Ox00000000, callx routine 
Oxb0815000, ldq (x5), gO 
Oxb0al6010, ldg 0x10(r5),g4 
Oxb0c16020, 1ldq 0x20(xr5),g8 
0xa0e16030, ldt 0x30(xr5),g12 
0x5c081605, mov x5, sp 
0x84003000, O0x00000000 bx _intExit 
RETURNS | 
pointer to new interrupt handler, or 
NULL if out of memory 
SEE ALSO 
intLib 


NAME 
intLockLevelSet( ) - set the current interrupt lock-out level 


SYNOPSIS 
VOID intLockLevelSet (nawLevel) 
int newLevel; /* new interrupt level */ 


DESCRIPTION 
This routine prepares the appropriate interrupt mask and stores it in the glo<uci.iias. 
bally accesible intLockMask. ‘ee 


SEE ALSO 
intLib 
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NAME : 
intLockLevelGet{ ) - get the current interrupt lock-out level 


SYNOPSIS 
int intLockLevelGet () 


DESCRIPTION 
This routine returns the interrupt level currently stored in the interrupt 
lockout mask. | 


SEE ALSO 
intLib 


NAME | 
intRestrict( ) - restrict interrupt context from using a routine 


SYNOPSIS 
STATUS intRestrict () 


DESCRIPTION | 
This routine returns OK if and only if we are executing in a task’s context 
and ERROR if called within an interrupt context. 


SEE ALSO 
intLib, INT_RESTRICT{ ) macro in intLib.h. 


RETURNS 
TRUE or FALSE 


NAME | 
intContext( ) - determine if we are in interrupt context or task context 


SYNOPSIS 
BOOL intContext () 
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DESCRIPTION 
This routine returns true if and only if we are executing in interrupt context 
and NOT in a meaningful task context. 


RETURNS 
TRUE or FALSE 


SEE ALSO 
intLib 


NAME 
intCount( ) - get current interrupt nesting depth 


SYNOPSIS 
int intCount () 


DESCRIPTION 
This routine returns the number of interrupts that are currently nested. 


CAVEAT 
While it may appear that intCount will never return a value greater than 31, 
remember that ISR’s may modify the interrupt mask to allow lower priority 
interrupts. 


RETURNS | 
number of nested interrupts 


SEE ALSO 
intLib 
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NAME 
intLock( ) - lock out interrupts 


SYNOPSIS 
int intLock () 
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DESCRIPTION 
This routine is used to disable interrupts. The interrupt level is set to the 
lock-out level (level 31 by default). The routine returns the previous inter- 
rupt level, and this should be restored by a call to intUnlock (2). 


IMPORTANT CAVEAT 

intLock can be called both from interrupt level and from task level. When 
called from a task context, the interrupt lock level is part of the task’s con- 
text. Locking out interrupts does not prevent rescheduling. Thus, if a task 
locks out interrupts and then invokes kernel services that cause the task to 
block (e.g. taskSuspend (2) or taskDelay (2)) or causes a higher priority task 
to be ready (e.g. semGive (2) or taskResume (2)), then rescheduling will 
occur and interrupts will be unlocked while other tasks run. Rescheduling 
may be explicitly disabled with taskLock (2). 


EXAMPLE 
oldLevel = intLock (); 
/* ,..work with interrupts locked out... * 
intUnlock (oldLevel); 


RETURNS 
previous interrupt level 


SEE ALSO 
intLib, intUnlock (2), taskLock (2) 


NAME 
intUnlock( ) - cancel effect of intLock 


SYNOPSIS 
int intUnlock (level) : 
int level; /* level to which to restore interrupts */ 


DESCRIPTION | 3 
This routine is used to re-enable interrupts that have been disabled by 
intLock (2). Use the level obtained from the preceding intLock (2) call. 


SEE ALSO 
intLib, intLock (2) 
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NAME 
intVecBaseSet( ) - set the vector base address 


SYNOPSIS 
VOID intVecBaseSet (baseAddr) 
FUNCPTR *baseAddr; /* new vector base address */ 


DESCRIPTION 
This routine sets the vector base address. The CPU's vector base register is 
set to the specified value, and subsequent calls to intVecGet/intVecSet will 
use this base address. The vector base address is fixed, until changed by 
calls to this routine. 


NOTE 
The interrupt vector table is located in sysALib.s and moving it by 
intVBaseSet would require resetting the processor. This is NOT YET 
IMPLEMENTED. 


For the 1960 microprocessor the vector base is cached on chip in the PRCB, 
so it cannot be set from this routine. 


SEE ALSO 
intLib, intVecBaseGet (2), intVecGet (2), int VecSet (2) 


NAME 
intVecBaseGet{ ) - get the vector base address 


SYNOPSIS 
FUNCPTR *intVecBaseGet () 


DESCRIPTION | 
This routine returns the current vector base address that has been set via the 


int VecBaseSet (2) routine. 


RETURNS 
current vector base address 


SEE ALSO : 
intLib, int VecBaseSet (2) 
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NAME 
intVecSet( ) - set CPU vector 


SYNOPSIS 
VOID intVecSet (vector, function) 
FUNCPIR *vector} /* vector offset */ 
FUNCPTR function; /* address to place in vector */ 


DESCRIPTION 
This routine sets the specified exception/interrupt vector to the specified 
address. The vector is specified as an offset into the CPU's vector table. 


NOTE 
i960 vectors 0-7 are illeagal vectors, use of them will put the vector in the 
priorities /pending portion of the table which will yield undesirable actions. 


The 80960CA caches the NMI vector in internal ram at system power up. 
This is where the vector is taken when the NMI occurs. Therefore, this rou- 
tine checks to see if the vector we are changing is the NMI vector, and writes 
it to internal ram if it is. 


SEE ALSO 
intLib, int VecBaseSet (2), intVecGet (2) 
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NAME 
intVecGet{ ) - get vector 


SYNOPSIS : 
FUNCPTR intVecGet (vector) 
FUNCPTR *vector; /* vector offset */ 


DESCRIPTION 
This routine returns the current value of the specified exception/interrupt 
vector. The vector is specified as an offset into the CPU’s vector table. 


NOTE 
For the i960 the interrupt table location is cached in the prcb on chip. The 
location is returned by intVecBaseGet (2) 
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RETURNS 
current value of specified vector 


SEE ALSO 
intLib, intVecSet (2), intVecBaseSet (2) 
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NAME 
ioLib - I/O interface library 


SYNOPSIS , 
creat( ) - create a file 
remove( ) - delete a file 
unlink() - delete a file 
delete( ) - delete a file 
open( ) - open a file 
close( ) - close a file 
rename() - change the name of a file 
read() - read bytes froma file or device 
write( ) - write bytes to a file 
ioctl() - perform a file-specific control function 
Iseek( ) - set file read/write pointer 
ioDefPathSet( ) - set the current default path 
ioDefPathGet( ) - get the current default path 
chdir(.) - set the current default path 
getcwd() - get the current default path 
getwad( ) - get the current default path 
ioGlobalStdSet( ) - set the fd for global standard input/output/error 
ioGlobalStdGet( ) - get the fd for global standard input/output /error 
ioTaskStdSet{ ) - set the fd for task standard input/output /error 
ioTaskStdGet{ ) - get the fd for task standard input/output/error | 


int creat (name, flag) 

STATUS remove (name) 

STATUS unlink (name) 

STATUS delete (name) 

int open (name, flags, mode) 
STATUS close (fd) 

STATUS rename (oldname, newname) 
int read (fd, buffer, maxbytes) 
int write (fd, buffer, nbytes) 
int ioctl (fd, function, arg) 
int lseek (fd, offset, whence) 
STATUS ioDefPathSet (name) 
VOID ioDefPathGet (pathname) 
STATUS chdir (pathname) 

char *getcwd (buffer, size) 
char *getwd (pathname) 
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VOID ioGlobalStdSet (stdFd, newfd) 

int ioGlobalStdGet (stdFd) 

VOID ioTaskStdSet (taskId, stdFd, newid) 
int ioTaskStdGet (taskId, stdFd) 


DESCRIPTION 
This library contains the interface to the basic I/O system. It includes: 


- Interfaces to the seven basic driver-provided functions: creat(), 
delete(), open(), close( ), read( ), write( ), and toctl{ ). 


- Interfaces to several file system functions: rename() and lIseek(). 
- Routines to set and get the current working directory. 
- Routines to assign task and global standard fds. 


FILE DESCRIPTORS 
At the basic I/O level, files are referred to by a file descriptor, or “fd”. An fd 
is a small integer returned by a call to open( ) or creat( ). The other basic I/O 
calls take an fd as a parmeter to specify the intended file. 


Three fds are reserved and have special meanings: 


0 - standard input 
1 - standard output 
2, - standard error output 


Vx960 allows two levels of redirection. First, there is a global assignment of 
the three standard fds. By default, tasks will use this global assignment. 
The global assignment of the three standard fds is controlled by the routines 
toGlobalStdSet{ ) and ioGlobalStdGet{ ). 


Second, individual tasks may override the global assignment of these fds 
with their own assignments that apply only to that task. The assignment of 
task-specific standard fds is as By the routines ioTaskStdSet() and 
ioTaskStdGet ). - 


INCLUDE FILE 
ioLib.h 
SEE ALSO 
iosLib, Programmer's Guide: Me System 
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NAME 
creat( ) - create a file 


SYNOPSIS 
int creat (name, flag) 
char ‘name; /* name of the file to create */ 
int flag; /* READ, WRITE, or UPDATE «/ 


DESCRIPTION | : 
This routine creates a file called name and opens it with a specified flag. The 
routine determines on which device to create the file, and then calls that 
create routine of the device driver to do most of the work. Therefore, much 
of what transpires is device/driver dependent. 


The parameter flag is set to READ, WRITE, or UPDATE for the duration that 
the file is open. To create NFS files with a UNIX chmod-type file mode, call 
open() with the file mode specified in the third argument. 


RETURNS 
A file descriptor number, or ERROR if a filename is not specified, the device 
does not exist, no fds are available (see iosInit()), or the driver returns 
ERROR. 


SEE ALSO 
ioLib, open( ), Programmer's Guide: I/O System 


NAME 
remove( ) - delete a file 


SYNOPSIS 


STATUS remove (name) 
char *name; /* name of the file to delete */ 


DESCRIPTION 
This routine deletes a specified file. It performs the same function as 
delete(). It is provided for ANSI compatibility. | 


RETURNS 
OK if there is no delete routine for the device or if the driver returns OK; 
ERROR if there is no such device or if the driver returns ERROR. 
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SEE ALSO 
ioLib, delete(), unlink( ), Programmer's Guide: I/O System 
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NAME 
unlink() - delete a file 


SYNOPSIS 
STATUS unlink (name) 
char “name; /* name of the file to delete */ 


DESCRIPTION 
This routine deletes a specified file. It performs the same function as 
delete(), and it is provided for POSIX compatibility. 


RETURNS 
OK if there is no delete routine for the device or the driver returns OK; 
ERROR if there is no such device or the driver returns ERROR. 


SEE ALSO 
ioLib, delete( ), remove( ), Programmer's Guide: I/O System 


NAME 
delete( ) - delete a file 


SYNOPSIS 
STATUS delete (name) 
char *name; /* name of the file to delete */ 


DESCRIPTION 
This routine deletes a specified file. The routine calls the driver for the par- 


ticular device on which the file is located to do the work. 


RETURNS 
OK if there is no delete routine for the device cr the driver returns OK; 
ERROR if there is no such device or the driver returns ERROR. 
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SEE ALSO 
ioLib, Programmer's Guide: I/O System 


NAME 
open( ) - open a file 
SYNOPSIS 
int open (name, flags, mode) 
char ‘*name; /* name of the file to open «/ 
int flags; /* READ, WRITE, UPDATE, or O CREAT */ 
int mode; /* mode of file to be created «/ 
/* (UNIX chmod style) s/f 
DESCRIPTION 


This routine opens a file for reading, writing, or updating, and returns an fd 
for that file. The arguments to open() are the filename and the type of 
access: 

READ (or O_RDONLY) 
WRITE (or O_WRONLY) 
UPDATE (or O_RDWR) 
TRUNC (or O_TRUNC) 


open for reading only 


open for writing only 


open for reading and writing 


open with 0 bytes 


In general, open() can only open pre-existing devices and files. However, 

for NFS network devices only, files can also be created with open() by per- 

forming a logical OR operation with O_CREAT and the flags argument. In 

this case, the file is created with a UNIX chmod-style file mode, as indicated 
$33 with mode. For example: 


fd = open ("/usr/myFile", O CREAT | O_RDWR, 0644); 


Only the NFS driver uses the mode argument. 


RETURNS 
A file descriptor number, or ERROR if a file name is not specified, the device 
does not exist, no fds are available (see iosInit()), or the driver returns 
ERROR. | | 


SEE ALSO 
io Lib, creat( ), Programmer's Guide: I/O System 
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NAME 
close() - close a file 


SYNOPSIS 
STATUS close (fd) 
int £d; /* file descriptor to close */ 


DESCRIPTION 
| This routine closes the specified file and frees the file descriptor. It calls the 
device driver to do the work. 


RETURNS 
Status of the driver close routine, or ERROR if the fd is invalid. 


SEE ALSO 
ioLib, Programmer's Guide: I/O System 


NAME 
rename( ) - change the name of a file 


SYNOPSIS 
STATUS rename (oldname, newname) 
char *oldname; /* name of file to rename */ 
char *newname; /* name with which to rename file */ 


DESCRIPTION 
This routine changes the name of a file from oldfile to newfile. 


RETURNS 
OK, or ERROR if the file could not be opened or renamed. 


SEE ALSO 
ioLib 
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NAME 
read( ) - read bytes from a file or device 
SYNOPSIS 
int read (fd, buffer, maxbytes) 
int fd; /* file descriptor from which to read */ 
char ‘buffer; /* pointer to buffer to receive bytes */ 
int maxbytes; /* max number of bytes to read into buffer */ 
DESCRIPTION 


This routine reads a number of bytes (less than or equal to maxbytes) from a 
specified fd and places them in buffer. It calls the device driver to do the 


work. 


RETURNS | 
The number of bytes read (between 1 and maxbytes, 0 if end of file), or 
ERROR if the fd does not exist or the driver returns ERROR. 


SEE ALSO 
ioLib, Programmer's Guide: I/O System 
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NAME 
write( ) - write bytes to a file 
SYNOPSIS 
int write (fd, buffer, nbytes) 
int fd; /* file descriptor on which to write «/ 
char ‘*buffer; /* buffer containing bytes to be written */ 
int nbytes; //* number of bytes to write «/ 
DESCRIPTION 


This routine writes nbytes bytes from buffer to a specified file descriptor fd. It 
calls the device driver to do the work. 


RETURNS | 
The number of bytes written (if not equal to nbytes, an error has occurred), or 
ERROR if the fd does not exist or the driver returns ERROR. 
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SEE ALSO 
ioLib, Programmer's Guide: I/O System 


NAME 
toctl( ) - perform a file-specific control function 
SYNOPSIS 
int ioctl (fd, function, arg) 
int fd; /* file descriptor «/ 
int function; /* function code «/ 
int arg; /* arbitrary argument */ 
DESCRIPTION 


This routine performs a device-specific function on a device. Most requests 
are passed on to the driver for handling. The following example, which 
places the filename of the fd in nameBuf, is handled at the I/O interface level: 


doctl (fd, FIOGETNAME, &nameBuf) 


Since the availability of ioctl( ) functions is driver specific, these functions 
are discussed separately in tyLib, pipeDrv, nfsDrv, dosFsLib, rt11FsLib, 
and rawFsLib. 


RETURNS 
The return value of the driver, or ERROR if the fd does not exist. 


SEE ALSO | 
ioLib, tyLib, pipeDrv, nfsDrv, dosFsLib, rt11FsLib, rawFsLib, 
Programmer's Guide: I/O System, Local File Systems 


NAME 
Iseek( ) - set file read/write pointer 


SYNOPSIS 
int lseek (fd, offset, whence) 
int fd; /« file descriptor «/ 
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long offset; /* new byte offset to seek to */ 
int whence; /* relative file position «/ 


DESCRIPTION 
This routine sets the file read/write pointer of file fd to offset. The argument 
whence, which affects the file position pointer, has three values: 


L_ SET - set to offset 

L_INCR _ - set to current position plus offset 

L_XTND .- set to the size of the file plus offset 

This routine calls ioctl() with functions FIOWHERE, FIONREAD, and 
FIOSEEK. 


RETURNS 
The new offset from the beginning of the file, or ERROR. 


SEE ALSO 
ioLib 
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NAME | 
ioDefPathSet{ ) - set the current default path 


SYNOPSIS 
STATUS ioDefPathSet (name) : 
char ‘*name; /* name of the new default device and path */ 


DESCRIPTION Ane | 
This routine sets the default I/O path.- All relative pathnames specified to 
the I/O system will be prepended with this pathname. This pathname must 
be an absolute pathname i.e., name must begin with an existing device name. 


RETURNS are 
OK, or ERROR if the first component of the pathname is not an existing dev- 


ice. 


SEE ALSO 
ioLib, ioDefPathGet( ), chdir( ), getcwd{ ) 
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NAME 


ioDefPathGet( ) - get the current default path 


SYNOPSIS 
VOID ioDefPathGet (pathname) 
char ‘pathname; /* where to return the name */ 


DESCRIPTION 
This routine copies the name of the current default path to pathname. The 
parameter pathname should be MAX_FILENAME_LENGTH characters long. 


RETURNS 
N/A: 


SEE ALSO 7 
ioLib, ioDefPathSet{ ), chdir( ), getcwd() 


NAME 
chdir( ) - set the current default path 


SYNOPSIS 
STATUS chdir (pathname) 
char *pathname; /* name of the new default path */ 


DESCRIPTION Nara leew 4 
This routine sets the default I/O. path. All relative pathnames specified to 
the I/O system will be prepended with this pathname. This pathname must 
be an absolute pathname i.e., name must begin with an existing device name. 


RETURNS 
OK, or ERROR if the first component of the pathname is not an existing dev- 
ice. 


SEE ALSO 
ioLib, toDefPathSet{ ), ioDefPathGekt, ), getcwd( ) 
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NAME 


getcwd{ ) - get the current default as 


SYNOPSIS 
char *getcwd (buffer, size) 
char ‘*buffer; /* where to return the pathname */ 
int size; /* gixe in bytes of buffer */ 


DESCRIPTION 
This routine copies the name of the current default path to buffer. It pro- 
vides the same functionality as ioDefPathGet( ) and is provided for compa- 
tibility the POSIX specification. 


RETURNS 
A pointer to the supplied buffer, or NULL if size is too small to hold the 
current default path. 


SEE ALSO 
ioLib, ioDefPathSet( ), ioDefPathGet{ ), chdir( ) 
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NAME 
getwd() - get the current default path 


SYNOPSIS 
char *getwd (pathname) 
char ‘pathname; /* where to return the pathname */ 


DESCRIPTION 
This routine copies the name of the current default path to pathname. It pro- 
vides the same functionality as ioDefPathGet() and getcwd(). It is pro- 
vided for compatibility with some older UNIX systems. 


The parameter pathname should be MAX_FILENAME_LENGTH characters 
long. 


RETURNS 
A pointer to the resulting path name. 
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SEE ALSO 
ioLib 


NAME | 
ioGlobalStdSet( ) - set the fd for global standard input/output/error 


SYNOPSIS 
VOID ioGlobalstdSet (stdFd, newFd) 
int stdFd; /* standard input (0), output (1), or error (2) */ 
int newFd; /* new underlying fd «/ 


DESCRIPTION | 
This routine changes the assignment of a specified global standard fd stdFd 
(0, 1, or, 2) to the specified underlying fd newFd. newFd should be an fd open 
to the desired device or file. All tasks will use this new assignment when 
doing I/O to stdFd, unless they have specified a task-specific standard fd 
(see ioTaskStdSet( )). If stdFd is not 0, 1, or 2, this routine has no effect. 


RETURNS 
N/A 


SEE ALSO 
ioLib, ioGlobalStdGet( ), ioTaskStdSet{ ) 


NAME 
ioGlobalStdGet( ) - get the fd for global standard input/output /error 


SYNOPSIS 
int ioGlobalStdGet (stdFd) 
int stdFd; /* standard input (0), output (1), or error (2) */ 


DESCRIPTION 
This routine returns the current underlying fd for global standard input, out- 
put, and error. 
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RETURNS 
The underlying global fd, or ERROR if stdFd is not 0, 1, or 2. 


SEE ALSO 
ioLib, ioGlobalStdSet{ ), ioTaskStdGet( ) 


NAME 


ioTaskStdSet{ ) - set the fd for task standard input/output /error 


SYNOPSIS 
VOID ioTaskStdSet (taskIid, stdFd, newFd) 
int taskId; /* id of task whose std fd is to be set (0 = self) */ 
int stdFd; /* standard input (0), output (1), ox error (2) */ 
int newFd; /* new underlying fd «/ 


DESCRIPTION 
This routine changes the assignment of a specified task-specific standard fd 
stdFd (0, 1, or, 2) to the specified underlying fd newFd. newFd should be an fd 
open to the desired device or file. The calling task will use this new assign- 
ment when doing I/O to stdFd, instead of the system-wide global assign- 
ment which is used by default. If stdFd is not 0, 1, or 2, this routine has no 
effect. 


This routine has no effect if it is called at interrupt level. 


RETURNS 
N/A 
SEE ALSO  » $88 Ais 
ioLib, ioGlobalStdGet{-), ioTaskStdGet( ) 


NAME | 
ioTaskStdGet{ ) - get the fd for task standard input/output/error 


SYNOPSIS 
int ioTaskStdGet (taskId, stdFd) 
int taskId; /* id of desired task (0 = self) */ 
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int stdFd; /* standard input (0), output (1), or error (2) */ 


DESCRIPTION 
This routine returns the current underlying fd for task-specific standard 
input, output, and error. 


RETURNS 
The underlying fd, or ERROR if sédFd is not 0, 1, or 2, or the routine is called 
at interrupt level 


SEE ALSO 
ioLib, ioGlobalStdGet( ), ioTaskStdSet{ ) 
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NAME 


iosLib - I/O system 


SYNOPSIS 
iosInit( ) - initialize the I/O system 
iosDrvInstall( ) - install anI/O driver 
iosDrvRemove( ) - remove an I/O driver 
iosDrvShow( ) - display a list of system drivers 
iosDevAdd() - add a device to the I/O system 
iosDevDelete( ) - delete a device from the I/O system 
iosDevFind( ) - find an I/O device in the device list 
iosDevShow( ) - display the list of devices in the system 
iosFdShow( ) - display a list of fd names in the system 
iosFdValue( ) - validate an open fd and return the driver-specific value 


STATUS iosInit (max_drivers, max_files, nullDevName) 

int LosDrvInstall (pCreate, pDelete, pOpen, pClose, pRead, pwWrite, pIoctl) 
STATUS iosDrvRemove (drvnum, forceClose) 

VOID iosDrvShow () 

STATUS iosDevAdd (pDevHdr, name, drvnum) 

VOID iosDevDelete (pDevHdr) 

DEV_HDR *iosDevFind (name, pNameTail) 

VOID LosDevShow () 

VOID iosFdShow () 

int iosFdvalue (fd) 


DESCRIPTION 
This library i is the driver-level iateviac: to the Vx960 I/O system. Its primary 
purpose is to route user I/O requests to the proper drivers, using the proper 
parameters. To do this, it‘keeps tables about the available drivers (e. ae 


names, open files). 


The I/O system should be initialized by calling iosInit() before any site | 
routines in iosLib. Each driver then installs itself by calling tosDrvInstall( ). 
The devices serviced by each driver are added to the I/O system with 
iosDevAdd{ ). 


The I/O system is described more fully in the chapter “I/O System’. 


SEE ALSO 
intLib, ioLib, Programmer's Guide: I/O System 
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NAME 
iosInit( ) - initialize the I/O system 
SYNOPSIS 


STATUS ilosInit (max_drivers, max_files, nullDevName) 
int max_drivers; /* Maximum number of drivers allowed */ 


int max files; /* Max number of files allowed open at once */ 
char ‘*nullDevName; /* Name of the null device (bit bucket) */ 
DESCRIPTION 


This routine initializes the I/O system. It must be called before any other 
I/O system routine. 


SEE ALSO 
iosLib 
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NAME 
iosDrvInstall( ) - install an I/O driver 


SYNOPSIS 
int iJosDrvInstall (pCreate, pDelete, pOpen, pClose, pRead, pwWrite, plIoctl) 

FUNCPTR pCreate; /* pointer to driver create function */ 
FUNCPTR pDelete; /* pointer to driver delete function */ 
FUNCPTR pOpen; /* pointer to driver open function */ 

FUNCPTR pClose; /* pointer to driver close function */. 
FUNCPIR pRead; /* pointer to driver read function */ — 
FUNCPTR pWrite; /* pointer to driver write function */. 
FUNCPTR pIoctl; /* pointer to driver ioctl function */ 


DESCRIPTION 
This routine should be called once by each I/O driver. It hooks up the vari- 
ous I/O service calls to the driver service routines, assigns the driver a 
number, and adds the driver to the driver table. 


RETURNS | 
The driver number of the new driver, or ERROR if there is no room for the 
driver. 
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SEE ALSO 
 josLib 


NAME 
iosDrvRemove( ) - remove an I/O driver 
SYNOPSIS 
STATUS iosDrvRemove (drvnum, forceClose) 
int drvnum; /* Number of the driver to remove. 
* Returned by iosDrvInstall */ 
BOOL forceClose; /* if TRUE, force closure of all open files */ 
DESCRIPTION 
This routine removes an I/O driver from the driver table that was added by 
iosDrvInstall( ). 
RETURNS 
OK, or ERROR if the driver has open files. 
SEE ALSO 
iosLib 


NAME 
iosDrvShow( ) - display a list of system drivers 


SYNOPSIS 
VOID iosDrvShow () 


DESCRIPTION 
This routine displays all the drivers in the driver list. 


RETURNS 
N/A 


SEE ALSO 
iosLib 
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NAME 
tosDevAdd( ) - add a device to the I/O system 


SYNOPSIS 
STATUS iosDevAdd (pDevHdr, name, drvnum) 
DEV_HDR *pDevHdr; /* Pointer to the device’s structure */ 
char *name} /* Name of the device */ 
int drvnum; /* Number of the servicing driver. 
* Returned by iosDrvInstall */ 


DESCRIPTION 
This routine adds a device to the I/O system device list, making the device 
available to subsequent open() and creat( ) calls. 


The parameter pDevHadr is a pointer to a DEV_HDR (defined in iosLib.h) 
which is used as the node in the device list. Usually this is the first item ina 
larger device structure for the specific device type. The parameters name 
and drunum are entered in pDevHdr. 


RETURNS 
OK, or ERROR if there is already a device with the specified name. 


SEE ALSO 
iosLib 


NAME 
iosDevDelete( ) - delete a device from the I/O system 


SYNOPSIS 
VOID iosDevDelete (pDevHdr) 
DEV_HDR ‘*pDevHdr; /* Pointer to the device’s structure */ 


DESCRIPTION 
This routine deletes a device from the I/O system device list, making it una- 
vailable to subsequent open() or creat() calls. No interaction with the 
driver occurs, and any fds open on the device or pending operations are 
unaffected. 


If the device was never added to the device list, unpredictable results may 
occur. 
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SEE ALSO 
iosLib 


NAME 
iosDevFind( ) - find an I/O device in the device list 


SYNOPSIS 
| DEV_EDR *iosDevFind (name, pNameTail) 
char *name}; /* Name of the device */ 
char ‘**pNameTail; /* Where to return ptr to tail of the name */ 


DESCRIPTION 
This routine searches the device list for a device whose name matches the 


first portion of name. If a device is found, iosDevFind() sets the character 
pointer pointed to by pNameTail to point to the first character in name follow- © 
ing the portion which matched the device name, and returns a pointer to the 
device. If the routine fails, it returns a pointer to the default device and sets 
pNameTail to point to the beginning of name. If there is no default device, 
iosDevFind() returns NULL. 


RETURNS 
A pointer to the device header, or NULL if the device is not found. 


SEE ALSO | 
iosLib, pathLib 
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NAME 
iosDevShow( ) - display the list of devices in the system 


SYNOPSIS | 
VOID iosDevShow () 


DESCRIPTION 
This routine displays a list of all the devices in the device list. 
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RETURNS 
N/A 


SEE ALSO | 
iosLib, devs 
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NAME 


iosFdShow( ) - display a list of fd names in the system 


SYNOPSIS 
VOID iosFdShow () 


DESCRIPTION 
This routine displays a list of all fds in the system. 


RETURNS 
N/A 


SEE ALSO 
iosLib, toctl( ) 


NAME ee 3 
tosFdValue( ) - validate an open fdiand return the driver-specific value 


SYNOPSIS Bode 
int iosFdValue (fd) eT 
int fd; /* fd to check */ 


DESCRIPTION , 
This routine checks to see if a file descriptor is valid and returns the driver- 


specific value. 


RETURNS | 
The driver-specific value, or ERROR if the fd is invalid. 


SEE ALSO 
iosLib 
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NAME 


kernelLib - Vx960 kernel library 


SYNOPSIS 
kernelInit( ) - initialize the kernel 
kernelVersion( ) - return the kernel revision string 
kernelTinteSlice( ) - enable round-robin selection 


VOID kernelInit (rootRtn, rootMemSize, pMemPoolStart, pMemPoolEnd, iowe 
char *kernelVersion () 
STATUS kernelTimeSlice (ticks) 


DESCRIPTION 
The Vx960 kernel provides tasking control services to an application. The 
libraries kernelLib, taskLib, semLib, tickLib, and wdLib comprise the ker- 
nel functionality. This library is the interface to the Vx960 kernel initializa- 
tion, revision information, and scheduling control. 


KERNEL INITIALIZATION 
The kernel must be initialized before any other kernel operation is per- 
formed. Normally kernel initialization is taken care of by the system confi- 
guration code in usrInit( ) in usrConfig.c. 


Kernel initialization consists of the following: 


(1) Defining the starting address and size of the system memory partition. 
The malloc() routine uses this partition to satisfy memory allocation 
requests of other facilities in Vx960. 


(2) Allocating the specified memory size for an interrupt stack. Interrupt 
service routines will use this stack unless the underlying architecture 
does not support a separate interrupt stack, in which case the service 
routine will use the stack of the interrupted task. 


(3) Specifying the interrupt lock-out level. Vx960 will not exceed the speci- 
fied level during any operation. The lock-out level is normally defined 
to mask the highest priority possible. However, in situations where 
extremely low interrupt latency is required, the lock-out level may be 
set to ensure timely response to the interrupt in question. Interrupt ser- 
vice routines handling interrupts of priority greater than the interrupt 
lock-out level may not call any Vx960 routine. 


Once the kernel initialization is complete, a root task is spawned with the 
specified entry point and stack size. The root entry point is normally 
usrRoot{) of the usrConfig.c module. The remaining Vx960 initialization 
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takes place in usrRoot{ ). 


ROUND-ROBIN SCHEDULING 
Round-robin scheduling allows the processor to be shared fairly by all tasks 
of the same priority. Without round-robin scheduling, when multiple tasks 
of equal priority must share the processor, a single non-blocking task can 
usurp the processor until preempted by a task of higher priority, thus never 
giving the other equal-priority tasks a chance to run. 


Round-robin scheduling is disabled by default. It can be enabled or disabled 
with the routine kernelTimeSlice( ), which takes a parameter for the “time 
slice” (or interval) that each task will be allowed to run before relinquishing 
the processor to another equal-priority task. If the parameter is zero, 
round-robin scheduling is turned off. Lf round-robin is enabled and preemp- 
tion is enabled for the executing task, the routine tickAnnounce( ) will incre- 
ment the task’s time-slice count. When the specified time-slice interval is 
completed, the counter is cleared and the task is placed at the tail of the list 
of tasks at its priority. New tasks joining a given priority group are placed 
at the tail of the group with a run-time counter initialized to zero. 


If a higher priority task preempts a task during its time-slice, the time-slice 
of the preempted task count is not changed for the duration of the preemp- 
tion. If preemption is disabled during round-robin scheduling, the time-slice 
count of the executing task is not incremented. 


SEE ALSO 
taskLib, intLib, Programmer's Guide: Basic OS 


NAME 
kernelInit( ) - initialize the kernel 


SYNOPSIS 
VOID kernelInit (rootRtn, rootMemSize, pMemPoolStart, pMemPoolEnd, 
intStackSize, lockOutLevel) 

FUNCPTR rootRtn; /* user start-up routine */ 
unsigned rootMemSize; /* memory for TCB and root stack */ 
char * pMemPoolStart; /* beginning of memory pool */ 
char * pMemPoolEnd; /« end of memory pool */ 
unsigned intStackSize; /* interrupt stack size */ 
int lockOutLevel; /* interrupt lock-out level (1-7) */ 
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DESCRIPTION | 
This routine initializes and starts the kernel. It should only be called once. 


The routine rootRin is the user's start-up code that subsequently initializes 
system facilities (ie, the I/O system, network). Typically, rootRin is 
usrRoot( ). | | 


Interrupts are enabled for the first time after kernelInit() exits. Vx960 will 
not exceed the specified interrupt lock-out level during any of its brief uses 
of interrupt locking as a means of mutual exclusion. 


The system memory partition is initialized by kernelInit() with the size set 
by pMemPoolStart and pMenPoolEnd. Architectures that support a separate 
interrupt stack will allocate a portion of memory starting at pMemPoolStart 
of intStackSize bytes for this purpose. 


RETURNS 
N/A 


SEE ALSO | 
kernelLib, intLockLevelSet{ ) 


NAME 
kernelVersion( ) - return the kernel revision string 


SYNOPSIS 
char *kernelVersion () 


DESCRIPTION os | 
This routine returns a string:which contains the current revision of the ker- 
nel. The string is of the form “Vx960 version x.y’, where *’x”’ corresponds to 

_the kernel major revision, and-“‘y’ corresponds to the kernel minor revision. 


RETURNS 
A pointer to a string of format “Vx960 version x.y”. 


SEE ALSO 
kermelLib 
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NAME 
kernelTimeSlice( ) - enable round-robin selection 


SYNOPSIS 
STATUS kernelTimeSlice (ticks) 
int ticks; /* time-slice in ticks or 0 to disable round-robin */ 


DESCRIPTION 
This routine enables round-robin selection among tasks of same priority and 
sets the system time-slice to ticks. Round-robin scheduling is disabled by 
default. A time-slice of zero ticks disables round-robin scheduling. 


See the manual entry on kernelLib for more information on round-robin 
scheduling. 


RETURNS 
OK always. 


SEE ALSO 
kernelLib 
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NAME 
ledLib - line-editing library 


SYNOPSIS | 
ledOpen( ) - create a new line-editor ID 
ledClose( ) - discard the line-editor ID 
ledRead{ ) - read a line with line-editing 
ledControl( ) - change the line-editor ID parameters 


int ledOpen (inFd, outFd, histSize) 

STATUS ledClose (led_id) 

int ledRead (led_id, string, maxBytes) 

VOID ledControl (led_id, inFd, outFd, histSize) 


DESCRIPTION 
This library provides a line-editing layer on top of a tty device. The shell 
uses this interface for its history-editing features. 


The shell history mechanism is similar to the UNIX Korn shell history facil- 
ity, with a built-in line-editor similar to UNIX vi that allows previously 
typed commands to be edited. The command h() displays the 20 most 
recent commands typed into the shell; old commands fall off the top as new 
ones are entered. 


To edit a command, type ESC to enter edit mode, and use the commands 
listed below. The ESC key switches the shell to edit mode. The RETURN 
key always gives the line to the shell from either editing or input mode. 


The following list is a summary of the commands available in edit mode. 


Movement and search commands: 


nG - Go to command number n. 

/s - Search for string s backward in history. 
?s - Search for string s forward in history. 

n - Repeat last search. 

N - Repeat last search in opposite direction. 
nk - Get nth previous shell command in history. 
n- - Same as “k’’. 

nj - Get nth next shell command in history. 
n+ - Same as “j’”. 

nh - Move left n characters. 

“H - Same as “h”’. 
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nl - Move right 2 characters. 

SPACE ~- Sameas“‘]”. 

nw - Move n words forward. 

nw - Move x blank-separated words forward. 

ne - Move to end of the nth next word. 

nE - Move to end of the nth next blank-separated word. 
nb - Move back n words. 

nB - Move back n blank-separated words. 

fc - Find character c, searching forward. 

Fc - Find character c, searching backward. 

. - Move cursor to first non-blank character in line. 
$ - Go to end of line. 

fe) - Go to beginning of line. 

Insert commands (input is expected until an ESC is typed): 
a - Append. 7 

A - Append at end of line. 

c SPACE - Change character. 

cl - Change character. 

cw - Change word. 

cc - Change entire line. 

c$ - Change everything from cursor to end of line. 
Cc - Same as “’c$”. 

S - Same as “‘cc”’. 

i - Insert. 

I - Insert at beginning of line. 

R - Type over characters. 

Editing commands: 

nx - Replace the following n characters with c. 

nx - Delete n characters starting at cursor. 

nx - Delete n characters to the left of the cursor. 

d SPACE - Delete character. 

dl - Delete character. 

dw - Delete word. 

dd - Delete entire line. 

d$ - Delete everything from cursor to end of line. 
D - Same as “d$”. 

p - Put last deletion after the cursor. 

P - Put last deletion before the cursor. 

u - Undo last command. 
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~ - Toggle case, lower to upper or vice versa. 


Special commands: 


“U - Delete line and leave edit mode. 
*, - Redraw line. 
“D - Complete symbol name. 
RETURN - Give line to shell and leave edit mode. 
The default value for n is 1. 
DEFICIENCIES 


Since the shell toggles between raw mode and line mode, type-ahead can be 
lost. The ESC, redraw, and non-printable characters are built-in. The EOF, 
backspace, and line-delete are not imported well from tyLib. Instead, the 
library tyLib should supply and/or support these characters via ioctl( ). 


“see commands do not take counts as users might expect. For example, 
“ni” will not insert whatever was entered n times. 


SEE ALSO 
Programmer's Guide: Shell 


NAME 


ledOpen() - create a new line-editor ID 


SYNOPSIS 2% : 

int ledOpen (inFa, sera -histSize) 
int dinFd; _/* lowtlevelidevice input fdi#/. fs. '* 
int outFd; /* low: level device output fd */ 
int histSize; /* size of history list */ 


DESCRIPTION 
This routine creates: the ID that is used by ledRead(), ledClose(), and 
ledControl( ). Storage is allocated for up to histSize previously read lines. 


RETURNS 
The line-editor ID, or ERROR if the routine runs out of memory. 


SEE ALSO 
ledLib 
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NAME 
ledClose() - discard the line-editor ID 


SYNOPSIS 
STATUS ledClose (led id) 
int led_id; /* ID returned by ledOpen */ 


DESCRIPTION 
This routine frees resources allocated by ledOpen(). The low-level 
input/output fds are not closed. 


SEE ALSO 
ledLib 


NAME 
ledRead() - read a line with line-editing 


SYNOPSIS 
int ledRead (led_id, string, maxBytes) 
int led_id; /* ID returned by ledOpen */ 
char *string; /* where to return line */ 
int maxBytes; i max imum number. of chars-to read */ 


DESCRIPTION | kad Sis 
This routine handles icsadads saa ashistoiyesbbstitutions.. ‘Ifthe low-level: ; 9. - 
input file descriptor is not in ae - er aa ne read: wetgetee a 
tine will be performed. 


RETURNS 
The number of characters read, or EOF. 


SEE ALSO 
ledLib 
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NAME 


ledControl( ) - change the line-editor ID parameters 


SYNOPSIS 


int led_id; 
int inFd; 

int outFd; 
int histSize; 


DESCRIPTION 


VOID ledControl (led_id, inFd, outFd, histSize) 


/* ID returned by ledOpen */ 

/* new input fd (NONE = no change) */ 

/* new output fd (NONE = no change) */ 

/* new history list size (NONE = no change) */ 
{* (0 = display) */ 


This routine changes the input/output file descriptor and the size of the his- 


tory list. 


RETURNS 
N/A 


SEE ALSO 
ledLib 
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NAME 


load Lib - object module loader 


SYNOPSIS 
loadModule( ) - load object module into memory 
loadModuleAt( ) - load object module into memory 


STATUS loadModule (fd, symFlag) , 
STATUS loadModuleAt (fd, symFlag, ppText, ppData, ppBss) 
idprintSegInfo (pSeg) | 


DESCRIPTION 
This library provides an object module loading facility. GNU/960 and b.out 
format files may be loaded into memory, relocated properly, their external 
references resolved, and their external definitions added to the system sym- 
bol table for use by other modules, and from the shell. Modules may be 
loaded from any I/O stream, anywhere in memory. 


EXAMPLE 
f£adX = open ("/devx/objFile", READ); 
loadModule (fdX, ALL SYMBOLS) ; 
close (fdX); 


This code fragment would load the b.out file objFile located on device 
/devX/ into memory which would be allocated from the system memory 
pool. All external and static definitions from the file would be added to the 
system symbol table. 


This could also have been accomplished from the shell, by typing: 
-> ld (1) </davx/objFile 


INCLUDE FILE 
loadLib.h 


SEE ALSO 
Programmer's Guide: Architecture usrLib, symLib, memLib 
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NAME | 
loadModule( ) - load object module into memory 
SYNOPSIS 
STATUS loadModule (fd, symFlag) 
int fd; /* £d of file to load */ 
int symFlag; /* symbols to be added to table 
* ({NO | GLOBAL | ALL]_SYMBOLS) */ 
DESCRIPTION | 
This routine loads an b.out format object module from the specified file, and 
placing the code, data and bss into memory allocated from the system 
memory pool. 
See loadModuleAt( ) for more detail. 
RETURNS 


OK, or ERROR if the file cannot be read, there is not enough memory, or the 
file format is illegal. 


SEE ALSO 
loadLib, loadModuleAt{( ) 


NAME 


loadModuleAt( ) - load object module into memory | 


SYNOPSIS ' & ; 
STATUS loadModuleAt (fd, symFlag, ppText,:ppData, ppBss) 
int £d; /* £d from which to read module */ 
int symFlag; /* symbols to be added to table 
* ((NO | GLOBAL | ALLJ SYMBOLS) */ 
INT8 **ppText; /* load text segment at adress pointed to by this 
* pointer, returm load address via this pointer */ 
INT8 **ppData; /* load data segment at adress pointed to by this 
* pointer, return load address via this pointer */ 
INT8 **ppBss; /* load bss seqment at adress pointed to by this 
* pointer, return load address via this pointer */ 
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DESCRIPTION 
This routine reads a b.out format object module from the specified fd, and 
loads the code, data and bss into memory at the specified load addresses, or 
into allocated memory as described below. The module is properly relo- 
cated as per the relocation commands in the file. Unresolved externals will 
be linked to symbols found in the system symbol table. Symbols in the 
module being loaded can optionally be added to system symbol table. 


LINKING UNRESOLVED EXTERNALS 

As the module is loaded, any unresolved external references are resolved by 
looking up the missing symbols in the the system symbol table. If found, 
those references are correctly linked to the new module. If unresolved exter- 
nal references can not be found in the system symbol table, then an error 
message (“undefined symbol: ...”) is printed for the symbol but the 
loading/linking continues. In this case, ERROR will be returned after the 
module is loaded. 


ADDING SYMBOLS TO THE SYMBOL TABLE 
The symbols defined in the module being loaded may ‘optionally be added 
to the system symbol table, depending on the value of symFlag. | 


NO_SYMBOLS - add no symbols to the system symbol table 
GLOBAL_SYMBOLS - add external symbols only 
ALL_SYMBOLS - add all symbols 


In addition, the following symbols ‘are:also added :toithe symbol-table-to.‘*: 
indicate the the start of each segment: filename_text, filename ed and 
filename_bss, where filename is the name associated with, the fd.. free TEREG TIALS 


RELOCATION 
The relocation commands in the object module are used. to- relocate thieitekctiiuciitle a 
data, and bss segments of the module. The location, of each’ segmentaait-bd he: igeae 
specified explicitly, or left unspecified in which: case. ‘memorys pall tbe Hire: as 
malloc’ed for the segment from the‘system memory pooliThisistdater astern Int 
mined by the parameters ppText, ppData, and ppBss at of which ‘carphawe/ at ARGO. 


the following values: 
NULL - no load address is specified, none will be seluitned arin Thbes 


ptr to LD_NO_ADDRESS 
- no load address is specified, return address via ptr 


ptr to address - load address is specified 


The ppText, ppData, and ppBss parameters are devious. For each one, if the 
pointer is NULL, the caller doesn’t care where the segment gets loaded, and 
doesn’t want to be told. If the pointer is not NULL, then the pointer points 
to a second pointer, which points to where the segment should be loaded. If 
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that second pointer has the value LD_NO_ADDRESS, then the caller doesn’t 
care where the segment gets loaded, but needs to be told where it was put. 
In that case, the LD NO_ADDRESS gets replaced with a pointer to where 
the segment got loaded. (LD_.NO_ADDRESS is used, rather than NULL, so 
that a segment may be loaded at the beginning of memory.) 


When either don’t care method is used, the corresponding segment is placed 
following the preceding segment (where the ordering of segments is text, 
data, bss). Thus, if ppText is don’t care, ppData indicates an actual address, 
and ppBss is don’t care, then space will be allocated for text, and bss will be 
placed following data. The caller is responsible for ensuring that the area 
indicated by ppData is large enough to contain both data and bss. 


COMMON 

Some host compiler/linker combinations internally use another storage 
class called ‘“common’”. In C, uninitialized global variables are eventually 
put in the BSS segment. However, in partially linked object modules they 
are flagged internally as ““common’” and the linker resolves these and places 
them in BSS as a final step in creating a fully linked object module. How- 
ever, the Vx960 loader is most often used to load object modules which are 
partially linked. When the Vx960 loader encounters a variable labeled as 
“common”, memory for the variable is allocated (with malloc) and the vari- 
able is entered in the system symbol table (if specified) at that address. Note 
that some loaders have an option that forces resolution of the “common” 
storage while leaving the module relocatable (e.g., with typical BSD UNIX 
loaders, use options “’-v’). 


NOTE 80960CA | 
This function reads a b.out format file generated by the GNU/960 toolchain 
loader. (See b_out.h and GNU/960 Reference Manua!). The b.out header 
fields are used as follows; 


a_tload - text runtime load address 
a_dload - data runtime load address 
a_talign - Alignment of text segment _ 
a_dalign - alingment of data segment 
a_balign - alignment of bss segment | 


If tload and dload are NULL, talign and dalign are checked and the seg- 
ments are located accordingly. If tload and dload are specified, it is the call- 
ers responsibilty to have them in aggreement with the given alignments. In 
effect, dalign and talign are ignored and only a_balign will be used to align 
the BSS segment accordingly. The BSS segment will be contiguous with the 
data segemnt, and padded by the appropriate number of bytes to make the 
alignment correct. 
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EXAMPLE | 
Load a module into allocated memory; do not return segment addresses: 


status = loadModuleAt (fd, GLOBAL _SYMBOLS, NULL, NULL, NULL); 


Load a module into allocated memory; return segment addresses: 


pText = pData = pBss = LD_NO_ADDRESS; 
status = loadModuleAt (fd, GLOBAL_SYMBOLS, &pText, &pData, &pBss); 


Load a module at a specified address: 


pText = 0x800000; /* address of text segment */ 
pData = pBss = LD NO ADDRESS /* other segments follow by default */ 
status = loadModuleAt (fd, GLOBAL_SYMBOLS, &pText, &pData, &pBss) ; 


RETURNS 
OK, or ERROR if the file cannot be read, there is not enough memory, or the 
file format is illegal. | 


SEE ALSO 
loadLib, Programmer's Guide: Architecture GNU/960 Reference Manual 
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NAME 


logLib - message logging library 


SYNOPSIS 


logInit( ) - initialize message logging library 
logMsg( ) - log a formatted error message 
logFdSet{ ) - set the primary logging file descriptor 
logFdAdd( ) - add a logging file descriptor 
logFdDelete( ) - delete a logging file descriptor 
logTask( ) - message-logging support task 


STATUS logInit (fd, maxMsgs) 

int logMsg (fmt, argl, arg2, arg3, arg4, arg5, arg6) 
VOID logFdSet (fd) 

STATUS logFdAdd (fd) 

STATUS logFdDelete (fd) 

VOID logTask () 


DESCRIPTION 


This module handles message logging. It is usually used to display error 
messages on the system console, but such messages can also be sent to a 
disk file or printer. 


The routines logMsg( ) and logTask() are the basic components of the log- 
ging system. The routine logMsg has the same calling sequence as printf( ), 


but instead of formatting and outputting the message directly, it sends the .. 


format string and arguments to a message queue. The task logTask() waits ..: . 


for messages on this message queue. It formats each message according to 


the format string and arguments in the message, prepends the ID of.,the |: 


sender, and writes it on one or more fds that have been specified. as'légging sens 


output streams (by oginit( ) or Ra set by logFdSet{)-'or *** 


logFdAdd{ )). 


USE IN INTERRUPT SERVICE ROUTINES 


Because logMsg( ) does not directly cause output to I/O devices but instead 
simply writes to a message queue, it can be called from an interrupt service 
routine as well as from tasks. Normal I/O, such as printf() output to a 
serial port, cannot be done from an interrupt service routine. 


DEFERRED LOGGING 


Print formatting is performed within the context of logTask( ) rather than the 
context of the task calling logMsg(). Since formatting can require consider- 
able stack space, this can reduce stack sizes for tasks that only need to do 
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I/O for error output. 


However, this also means that the arguments to logMsg() are not inter- 
preted at the time of the call to JogMsg(), but rather are interpreted at some 
later time by logTask( ). This means that the arguments to logMsg( ) should 
not be pointers to volatile entities. For example, pointers to dynamic or 
changing strings and buffers should not be passed as arguments to be for- 
matted. Thus the following would not give the desired results: 


doLog (which) 


{ | 
char string [100]; 


strcpy (string, which ? “hello” : “goodbye”) ; 


logMsg (string); 
} 


By the time logTask( ) formats the message, the stack frame of the caller may 
no longer exist and the pointer string may no longer be valid. On the other 
hand, the following is correct since the string pointer passed to the 
logTask( ) always points to a static string: 


doLog (which) 
{ 
char *string; 


string = which ? “hello” : "goodbye" ; 


logisg (string); 
} 
INITIALIZATION 
To initialize the message logging facilities, the routine logInit() must be . 
called before any other routines in this module. This is done Py the root 
task, usrRoot( ), in usrConfig.c. | 


SEE ALSO | 
fioLib, pipeDrv, Programmer's Guide: I/O System 
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NAME 


logInit( ) - initialize message logging library 


SYNOPSIS 


STATUS logInit (fd, maxdsgs) 
int fd; /* file descriptor to use as logging device */ 
int maxMsgs; /* maximum number of messages allowed in * 


* the log queue */ 


DESCRIPTION 
This routine specifies the fd to be used as the logging device and the number 
of messages that can be in the logging queue. If more than maxMsgs are in 
the queue, they will be discarded. A message is printed to indicate lost mes- 
sages. 


This routine spawns logTask( ), the task-level portion of error logging. 


This routine must be called before any other routine in logLib. This is done 
by the root task, usrRoot( ), in usrConfig.c. 


RETURNS 
OK, or ERROR if a message queue could not be created or logTask() could 
not be spawned. 


SEE ALSO 
logLib 


NAME 


logMsg( ) - log a formatted error message 


SYNOPSIS 
int logMseg (fmt, argl, arg2, arg3, arg4, argS, arg6) 
char ‘*fmt; /* format string for print */ 
int argl; /* optional arguments for fet */ 


int arg2; 
int arg3; 
int arg4; 
int arg5; 
int arg6; 
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DESCRIPTION 
This routine logs the specified message via the logging task. Its syntax is 
identical to print{() — a format string is followed by arguments to be filled 
in the format. However, the JogMsg( ) routine is restricted to a maximum of 
6 arguments following the format string. 


The task ID of the caller is prepended to the specified message. 


SPECIAL CONSIDERATIONS 
Because IogMsg{ ) does not actually perform the output directly to the log- 
ging streams, but instead queues the message to the logging task, logMsg( ) 
can be called from interrupt service routines. 


However, since the arguments are interpreted by the logTask() at the time 
of actual logging, instead of at the moment when logMsg{( ) is called, argu- 
ments to logMsg( ) should not be pointers to volatile entities (e.g., dynamic 
strings on the caller stack). 

See the manual entry for logLib for more detailed information about the use 
of logMsg{ ). 


EXAMPLE 
If the following code were executed by task 20: 


{ 
name = "GROMNK"; 
num = 123; 


logHag ("ERROR - name = ts, num = td.\n", name, num); 
} 

the following error message would appear on the system log: 
t20: BRROR - names = GROKK, num = 123. 


RETURNS 
The number of bytes written to the log queue, or EOF if the routine is unable 


to write a message. 


SEE ALSO 
logLib, printf() 
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NAME 


logFdSet{ ) - set the primary logging file descriptor 


SYNOPSIS | 
VOID logFdSet (fd) 
int fd; /* file descriptor to use as logging device */ 


DESCRIPTION 

: This routine changes the fd where messages from logMsg() are written, 
allowing the log device to be changed from the default specified by 
logInit( ). It first removes the old fd (if one had been previously set) from 


the log fd list, then adds the new fd. | 


The old logging fd is not closed or affected by this call; it is simply no longer 
used by the logging facilities. | 


RETURNS 
N/A 


SEE ALSO | 
logLib, logFdAdd{ ), logFdDelete( 


NAME 


logFdAdd( ) - add a logging file descriptor 


SYNOPSIS 
STATUS logFdAdd (fd) . 
int fd; /* file descriptor for additional logging device */ 


DESCRIPTION 


This routine adds another fd to which messages will be logged to the log fd 
list. The fd must be a valid open fd. 


RETURNS 
OK, or ERROR if the allowable number of additional logging fds (5) is 


exceeded. 


| SEE ALSO 
logLib 
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NAME 
logFdDelete( ) - delete a logging file descriptor 


SYNOPSIS 
STATUS logFdDelete (fd) 
int fd; /* file descriptor to stop using as logging device */ 


DESCRIPTION 
This routine removes a logging fd added by logFdAdd( ) from the log fd list. 
The fd is not closed; it is simply no longer used by the logging facilities. 


RETURNS 
OK, or ERROR if the fd was not added with logFdAdd{ ). 


SEE ALSO 
logLib, logFdAdd{ ) 


NAME 


logTask( ) - message-logging support task 


SYNOPSIS 
VOID logTask () 


DESCRIPTION 
This task prints the messages logged. with logMsg( ). It continually reads a 
pipe and prints any messagesthat:come through the pipe in log format on 
the fd that was specified by foginit() (or a subsequent call to logFdSet{ ) or 
logFdAdd( )). 


This task is spawned by logIntt( ). 


RETURNS 
N/A 


SEE ALSO 
logLib 
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NAME 
loginLib - user login/password subroutine library 


SYNOPSIS 
loginInit( ) - initialize the login table 
loginUserAdd( ) - add a user to the login table 
loginUserDelete() - delete a user entry from the login table _ 
loginUserVerify( ) - verify a user name and password in the login table 
loginUserShow( ) - display the user login table 
loginPrompt( ) - display a login prompt and validate a user entry 
loginStringSet( ) - change the login string 
loginEncryptInstall( ) - install an encryption routine 
loginDefaultEncrypt( ) - default password encryption routine 


VOID loginInit () 

STATUS loginUserAdd (name, passwd) 

STATUS loginUserDelete (name, passwd) ... 
STATUS loginUserVerify (name, passwd) 
VOID loginUserShow () 

STATUS loginPrompt (userName) eee 

VOID loginStringSet (newString) 

VOID loginEncryptInstall (rtn, var) 
STATUS loginDefaultEncrypt (in, out) 


DESCRIPTION | 
This library provides a login/password facility for network access to the 
Vx960 shell. When installed, it will require a user name and password match 
to gain access to the Vx960 shell from rlogin or telnet. This permits Vx960 to 
be used in secure environments that must restrict access to a Vx960 system. 


A routine is provided to prompt for the user name and password, and to 
verify the response by looking up the name/password pair in a login user 
table. This table contains a list of user names and encrypted passwords that 
will be allowed to remotely login to a Vx960 shell. Routines are provided to 
add, delete, and access the login user table. The list of user names can be 
displayed with loginUserShow{ ). 


INSTALLATION 
The login security feature is initialized by calling loginInit(). The login 
feature must then be connected to the shell by calling shellLoginInstall{ ). 


loginInit (); /* initialize login table * 
shelllLoginInstall (loginPrompt, NULL); /* install security program * 
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If INCLUDE_SECURITY is defined in configAll.h, these routines are called 
by usrRoot( ) in usrConfig.c. 


The name/password pairs are added to the table by calling loginUserAdd( ), 
which takes the name and an encrypted password as arguments. The Vx960 
host tool vxencrypt is used to generate the encrypted form of a password. 
For example, to add a user name of “fred” and password of “’flintstone”, 
first run vxencrypt on the host to find the encryption of “‘flintstone”’ as fol- 
lows: 

% vxencrypt 


please enter password: flintstone 
encrypted password is ScebRezb9c 


Then invoke the routine loginUserAdd( ) in Vx960: 
loginUserAdd ("fred", “ScebRezb9c"); 


This can be done from the shell, a start-up script, or application code. 


In the standard Vx960 configuration, the login security feature is included in 
a Vx960 system by defining INCLUDE _SECURITY in configAll.h. This will 
enable the calls to loginInit() and shellLoginInstall(), in the Vx960 confi- 
guration module usrConfig.c. It also adds a single default user to the login 
table. The default user and password are defined in configAll.h as 
LOGIN_USER_NAME and LOGIN_PASSWORD. These can be set to any 
desired name and password. Additional users can be added by adding addi- 
tional calls to loginUserAdd{ ). 


LOGGING IN 
When the login security facility is installed, every attempt to rlogin or telnet 
to the Vx960 shell will first prompt for user name and password. 


& rlogin target 


Vx960 login: fred 
Password: flintstone 


=-> 


The delay in prompting between unsuccessful logins is increased linearly 
with the number of attempts, in order to slow down password-guessing 
programs. 


ENCRYPTION ALGORITHM 
This library provides a simple default encryption routine, 
loginDefaultEncrypt(). This algorithm requires that passwords be at least 8 
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characters and no more than 40 characters. | 


The routine loginEncryptInstall() allows a user-specified encryption func- 
tion to be used instead of the default. 


INCLUDE FILES 
loginLib.h 


SEE ALSO 
shellLib, vxencrypt 


NAME 
loginInit( ) - initialize the login table 


SYNOPSIS 
VOID loginInit () 


DESCRIPTION 
This routine must be called to initialize the login data structure used by rou- 
tines throughout this module. If INCLUDE_SECURITY is defined in 
configAILh, it is called by usrRoot( ) in usrConfig.c, before any other rou- 
tines in this module. 


RETURNS 
N/A 


SEE ALSO 
loginLib 


NAME 


loginUserAdd{ ) - adda user to the login table 


SYNOPSIS 
STATUS loginUserAdd (name, passwd) 
char name[MAX_LOGIN NAME LEN+1]; /* user name */ 
char passwd([80]}; /* user password */ 
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DESCRIPTION 
This routine adds a user name and password entry to the login table. 


The length of user names should not exceed MAX_LOGIN_NAME LEN, 
while the length of passwords depends on the encryption routine used. For 
the default encryption routine, passwords should be at least 8 characters 
long and no more than 40 characters. 


The procedure for adding a new user to login table is as follows: 
(1) ~~ Generate the encrypted password by invoking vxencrypt in vw/bin. 


(2) Adda user by invoking loginUserAdd() in the Vx960 shell with the 
user name and the encrypted password. 


The password of a user can be changed by first deleting the user entry and 
then adding the user entry again with the new encrypted password. 


EXAMPLE 
~> loginUserAdd “peter”, “RRdRd9Qbyz" 
value = 0 = 0x0 
-> loginUserAdd “robin", “bSzyydqbSb“ 
value = 0 = 0x0 
-> loginUserShow 


User Name 


peter 

robin 
value = 0 = 0x0 
-> 


RETURNS a a ee 
OK, or ERROR if the user name has‘already been éntereds 


SEE ALSO ; 8 ABBE 
loginLib, vxencrypt taginiloy wrerace: 


NAME 7 | 
loginUserDelete( ) - delete a user entry from the login table 


SYNOPSIS 
STATUS loginUserDelete (name, passwd) 
char ‘*name; /* user name */ 
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char ‘*passwd; /* user password */ 


DESCRIPTION 
This routine deletes an entry in the login table, Both the user name and 
password must be supplied to remove an entry from the login table. 


RETURNS 
OK, or ERROR if there is no such user or the password is incorrect. 


SEE ALSO | 
loginLib 


NAME 
loginUserVerify( ) - verify a user name and password in the login table 
SYNOPSIS 
| STATUS loginUserVerify (name, passwd) 
char *name; /* name of user */ 
char *passwd; /* password of user */ 
RETURNS 
OK, or ERROR if the user name or password is not found. 
SEE ALSO 
loginLib 


NAME | 

loginUserShow( ) - display the user login table 
SYNOPSIS 

VOID loginUserShow () 
DESCRIPTION 

This routine displays valid user names. 
EXAMPLE 


-> loginUserShow () 


User Name 
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peter 

robin 
value = 0 = 0x0 
-> 


RETURNS 
N/A 


SEE ALSO 
loginLib 


NAME . 
loginPrompt( ) - display a login prompt and validate a user entry 


SYNOPSIS 
STATUS loginPrompt (userName) 
char ‘userName; /* user name, ask if NULL or not provided */ 


DESCRIPTION 
This routine displays a login prompt and validates a user entry. If both user 
name and password match with an entry in the login table, the user is then 
given access to the Vx960 system. Otherwise, it will prompt the user again. 


All control characters are disabled during authentication except “D, which 
will terminate the remote er session. 


RETURNS 
OK if the name and aiiaed are valid, or ERROR if there is an EOF or the 
routine times out. 


SEE ALSO 
loginLib 
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NAME 
loginStringSet( ) - change the login string 


SYNOPSIS wer 
VOID loginStringSet (newString) 
char ‘*newString; /* string to become new login prompt */ 


DESCRIPTION 


This routine changes the login prompt string to newString. The maximum 
string length is 80 characters. 


RETURNS 
N/A 


SEE ALSO 
loginLib 
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NAME 
loginEncryptInstall( ) - install an encryption routine 


SYNOPSIS 
VOID loginEncryptInstall (rtn, var) 
FUNCPTR rtn; /* function pointer‘tg encryption routine */' 
int var} /* argument to the encryption routine :(unused)~*/~*~" 


DESCRIPTION : mee 


tom routine rin must be of the following’ form: (see the manual entry for 
loginDefaultEncrypt( )): : 


STATUS encryptRoutine (password, encryptedPassword) 
char *password} | /* string to encrypt * 
char *encryptedPassword; /* resulting encryption * 


When a custom encryption routine is installed, a UNIX version of this rou- 
tine should also replace the tool vxencrypt in vw/bin. When a user logs in to 
the system, rtn is invoked to encrypt the requested password. The 
encrypted password is then compared against the encryption that was gen- 
erated by the custom version of vxencrypt and added to Vx960 via 
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loginUserAdd({ ). 


EXAMPLE 
The custom example above could be installed as follows: 


#ifdef INCLUDE_SECURITY 
loginInit (); /* initialize login table * 
shellLoginInstall (loginPrompt, NULL); /* install shell security * 
loginEncryptInstall (encryptRoutine, NULL); /* install encryption 
routine * 
fendif 


RETURNS 
N/A 


SEE ALSO 
loginLib, loginDefaultEncrypt( ), vxencrypt 
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NAME 
loginDefaultEncrypt( ) - default password encryption routine 


SYNOPSIS 
STATUS loginDefaultEncrypt (in, out) 
char *in; /* input string */ 
char ‘*out; /* encrypted string */ 


DESCRIPTION 
This is the default sierpption contin It Lensinn a simple éncryptioncalgo-:~ fe 
rithm. As arguments, it takes a string in and a pointer. to a: buffersbut,cThe:: ua pe 


: r 


encrypted string is then stored inthe buffer. ~~ , ftevecin the but 


The input strings must be at least 8 characters and no more than:40 ‘charac... = 
ters. : 


If a more sophisticated encryption algorithm is needed, this routine canbe” 
replaced, as long as the new encryption routine retains the same declara- 
tions as the default routine. The routine vxencrypt in vw/bin should also be 
replaced by a UNIX version of encryptionRoutine. For more information, see 
the manual entry for loginEncryptInstall( ). 


RETURNS 
OK, or ERROR if the password is invalid. 


Rev: 29 Aug 91 Intel 1 - 205 


Vx960 5:0 - = - Reference-Manuat ~ Reletencs ManuUol ~ 


SEE ALSO 
loginLib, loginEncryptIustall( ), vxencrypt 
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NAME 
IstLib - doubly linked list subroutine library 


SYNOPSIS 

' IstInit( ) - initialize a list descriptor 
IstAdd() - add a node to the end of a list 
IstConcat( ) - concatenate two lists 
IstCount( ) - report the number of nodes in a list 
IstDelete( ) - delete a specified node froma list 
IstExtract( ) - extract a sublist from a list 
IstFirst() - find first node in list 
IstGet( ) - delete and return the first node from a list 
IstInsert( ) - insert a node ina list after a specified node 
IstLast() - find the last node ina list 
IstNext() - find the next node in a list 
IstNth( ) - find the Nth node ina list 
IstPrevious{ ) - find the previous node in a list 
IstNStep( ) - find a list node nStep nodes away from a specified node 
IstFind() - find a node ina list 
IstFree( ) - free up a list 


VOID lstInit (plist) 

VOID lstAdd (plist, pNode) 

VOID 1lstConcat (pDstList, pAddList) 
int lstCount (plist) 

VOID lstDelete (pList, pNode) 

VOID lstExtract (pSrcList, pStartNode, pEndNode, pDstList) 
NODE *lstFirst (pList) 

HODE *lstGet (pList) 

VOID lstInsert (plist, pPrev, sueaase 
NODE *lstLast (plist) 

NODE *lstNext (pNode) 

NODE *lstNth (pList, nodenum) 

NODE *lstPrevious (pNode) 

NODE *lstNStep (pNode, nStep) 

int lstFind (pList, pNode) 

VOID lstFree (plist) 


DESCRIPTION | 
This subroutine library supports the creation and maintenance of a doubly 
linked list. The user supplies a list descriptor (type LIST) that will contain 
pointers to the first and last nodes in the list, and a count of the number of 
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nodes in the list. The nodes in the list can be any user-defined structure, but 
they must reserve space for two pointers as their first elements. Both the 
forward and backward chains are terminated with a NULL pointer. 


The linked-list library simply manipulates the linked-list data structures; no 
kernel functions are invoked. In particular, linked lists by themselves pro- 
vide no task synchronization or mutual exclusion. If multiple tasks will 
access a single linked list, that list must be guarded with some mutual- 
exclusion mechanism (e.g., a mutual-exclusion semaphore). 


NON-EMPTY LIST 


| head------—-------- >| next--------- -->| next----~----- 
| | | | | | | 
| _— prev [<---------- prev | | 
| | | | | | | | | 
[ tail—.... i | eee | ----->| eee | | 
| | Vv { Vv 
|count=2{ | ----- ee 
--------—- | saat | ates 
[| - | . 
| | 
EMPTY LIST 
| head-------------~----- 
| | | 
| tail---------- | 
| | | v 
| count=0 | ----- ----- 


INCLUDE FILE 
IstLib.h te 


NAME 
IstInit( ) - initialize a list descriptor 


SYNOPSIS 
VOID lstInit (pList) 
LIST ‘*pList; /* pointer to list descriptor to be initialized */ 
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DESCRIPTION 
This routine initializes a specified list to an empty list. 


RETURNS 
N/A 


SEE ALSO 
IstLib 


NAME 
IstAda() - adda node to the end of a list 


SYNOPSIS 
VOID lstAdd (pList, pNode) 
LIST *pList; /* pointer to list descriptor */ 
RODE *pNode; /* pointer to node to be added */ 


DESCRIPTION — 
This routine adds a specified node to the end of a specified list. 


RETURNS 
N/A 


SEE ALSO 
IstLib 


NAME 
IstConcat( ) - concatenate two lists 


SYNOPSIS 
VOID lstConcat (pDstList, pAddList) 
LIST ‘*pDstList; /* Destination list */ 
LIST *pAddList; /* List to be added to dstList */ 


DESCRIPTION 
This routine concatenates the second list to the end of the first list. The 
second list is left empty. Either list (or both) can be empty at the beginning 
of the operation. 
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RETURNS 
N/A 


SEE ALSO 
IstLib 


NAME 


IstCount( ) - report the number of nodes ina list 


SYNOPSIS 
int lstCount (pList) 
LIST “plist; /* pointer to list descriptor */ 


DESCRIPTION 
This routine returns the number of nodes in a specified list. 


RETURNS 
The number of nodes in the list. 


SEE ALSO 
IstLib 


NAME _ ae 
IstDelete( ) - delete aspecifiedaiodp-from ia listocciticd noc: 
SYNOPSIS. Se 
| VOID IlstDelete (plist, pNode) - : " 
LIST *pList; /* pointer to list descriptor */ 
NODE *pNode; /* pointer to node to be deleted */ 
DESCRIPTION 
This routine deletes a specified node from a specified list. 
RETURNS 
N/A 
1-210 Intel 
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NAME 
IstExtract( ) - extract a sublist from a list 


SYNOPSIS 
VOID istExtract (pSrcList, pStartNode, pEndNode, pDstList) 
LIST *pSrcList; /* pointer to source list */ 
NODE *pStartNode; /* first node in sublist to be 
* extracted */ 
NODE *pEndNode; /* last node in sublist to be 
* extracted */ 
LIST *pDstList; /* pointer to list where to put 
* extracted list */_ 


DESCRIPTION 
This routine extracts the sublist that starts with pStartNode and ends with 
pEndNode from a source list. It places the extracted list in pDstList. 


RETURNS 
N/A 


SEE ALSO 
IstLib 


NAME 
IstFirst() - find first node in list 


SYNOPSIS 
NODE *lsatFirst (pList) 
LIST *pList; /* pointer to list descriptor */ 


DESCRIPTION 
This routine finds the first node in a linked List. 
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RETURNS 
A pointer to the first node ina list, or NULL if the list is empty. 


SEE ALSO 
IstLib 


Meer ne 


NAME 
IstGet( ) - delete and return the first node froma list 


SYNOPSIS 
NODE *lstGet (pList) 
LIST *pList; /* pointer to list from which to get node */ 


DESCRIPTION 
This routine gets the first node from a specified list, deletes the node from 
the list, and returns a pointer to the node gotten. 


RETURNS 
A pointer to the node gotten, or NULL if the list is empty. 


SEE ALSO 
AstLib 


NAME 
IstInsert( ) - insert a node ina list after a specified node 


SYNOPSIS 
VOID IstInsert (pList, pPrev, pNode) 
LIST *pList; /* pointer to list descriptor */ 
NODE ‘*pPrev; /* pointer to node after which to insert */ 
NODE ‘“pNode; /* pointer to node to be inserted */ 


DESCRIPTION 
This routine inserts a specified node in a specified list. The new node is 
placed following the list node pPrev. Lf pPrev is NULL, the node is inserted at 


the head of the list. 
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RETURNS 
N/A 


SEE ALSO 
IstLib 


NAME 
IstLast() - find the last node in a list 


SYNOPSIS 
WODE *lstLast (plist) 
LIST *pList; /* pointer to list descriptor */ 


DESCRIPTION 
This routine finds the last node ina list. 


RETURNS 
A pointer to the last node in the list, or NULL if the list is empty. 


SEE ALSO 
IstLib 


NAME 


IstNext( ) - find the next node ina list 


SYNOPSIS 
WODE *lstNext (pNode) 
RODE *pNode; /* pointer to node whose successor 
* is to be found */ 


DESCRIPTION 
This routine locates the node immediately following a specified node. 


RETURNS 
A pointer to the next node in the list, or NULL if there is no next node. 
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NAME 
IstNth( ) - find the Nth node in a list 


SYNOPSIS 
NODE *lstNth (pList, nodenum) | 
LIST *pList; /* pointer to list descriptor */ 
int nodenum; /* number of node to be found */ 


DESCRIPTION 
This routine returns a pointer to the node specified by a number nodenum 
where the first node in the list is numbered. Note that the search is optim- 
ized by searching forward from the beginning if the node is closer to the 
head, and searching back from the end if it is closer to the tail. 


RETURNS 
A pointer to the Nth node, or NULL if there is no Nth node. 


SEE ALSO 
IstLib 


NAME 2 hers 
IstPrevious{ ) - find the previous nodeindalist:’.;, 9° = °° vr 


SYNOPSIS 
NODE *lstPrevious (pNode) | | 
RODE ‘*pNode; /* pointer to node whose predecessor is 
* to be found */ 


DESCRIPTION | 
This routine locates the node immediately preceding the node pointed to by 


pNode. 
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RETURNS 
A pointer to the previous node in the list, or NULL if there is no previous 
node. 

SEE ALSO 
IstLib 


NAME 
IstNStep( ) - find a list node nStep nodes away from a specified node 


SYNOPSIS 
NODE “lstNStep (pNode, nStep) 
NODE ‘*pNode; /* the known node */ 
int nStep; /* number of steps away to find */ 


DESCRIPTION . ode ET 
This routine locates the node nStep steps away in either direction from a 
specified node. If nStep is positive, it steps toward the tail. If nStep is nega- 
tive, it steps toward the head. If the number of steps is out of range, a NULL 


is returned. 
RETURNS 
A pointer to the node nStep steps away, or NULL if the node is out of range. 
SEE ALSO . 
IstLib " 
MMP EEE EEE 


NAME 


IstFind() - find a node ina list 


SYNOPSIS 
int lstFind (pList, pNode) 
LIST *pList; /* list in which to search */ 
RODE ‘*pNode; /* pointer to node to search for */ 
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DESCRIPTION 


This routine returns the node number of a specified node (the first node is 
1). 


RETURNS | 
The node number, or ERROR if the node is not found. 


SEE ALSO 


IstLib 


NAME 
IstFree( ) - free up a list 


SYNOPSIS 
VOID lstFree (pList) | 
LIST ‘“*pList; /* list for which to free all nodes */ 


DESCRIPTION 
This routine turns any list into an empty list. It also frees up memory used 


for nodes. 


RETURNS 
N/A 


SEE ALSO 
IstLib, free( ) 
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NAME 
mem Lib - the Vx960 memory manager 


SYNOPSIS 
memPartCreate( ) - create a memory partition 
mentPartAddToPool( ) - add memory to a memory partition 
memPartOptionsSet( ) - set the debug options for a memory partition 
memPartAlloc( ) - allocate a block of memory froma specified partition 
memPartRealloc( ) - reallocate a block of memory in a specified partition 
memPartFree( ) - free a block of memory ina specified partition 
menPartFindMax( ) - find the size of the largest available free block 
memPartShow( ) - show the partition blocks and statistics 
memtAddToPool( )- add memory to the system memory partition 
memOptionsSet() - set the debug options for the system memory partition 
nialloc( ) - allocate a block of memory from the system memory partition 
calloc( ) - allocate space for an array 
realloc( ) - reallocate a block of memory 
free( ) - free a block of memory 
cfree() - free a block of memory 
memFindMax( ) - find the largest free block in the system memory partition 
memShow( ) - show the system memory partition blocks and statistics 


PART_ID memPartCreate (pPool, poolSize) 
STATUS memPartAddToPool (partId, pPool, poolSize) 
STATUS memPartOptionsSet (partId, options) 
VOID *memPartAlloc (partId, nBytes) 

VOID *memPartRealloc (partId, pBlock, nBytes) 
STATUS memPartFree (partId, pBlock) 

int memPartFindMax (partId) 

STATUS memPartShow (partId, type) 

VOID memAddToPool (pPool, poolSize) 

VOID memOptionsSet (options) 

VOID *malloc (nBytes) | 

VOID *calloc (elemNum, elemSize) 

VOID *realloc (pBlock, newSize) 

STATUS free (pBlock) 

STATUS cfree (pBlock) 

int memFindMax () 

VOID memShow (type) 
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DESCRIPTION 

This library provides facilities for managing the allocation of blocks of 
memory from ranges of memory called memory partitions. This library con- 
sists of two sets of routines. The first set, memPart...(), comprises a general 
facility for the creation and deletion of memory partitions, and the allocation 
and deallocation of blocks from those partitions. The second set provides a 
traditional C malloc( )/free() interface to one particular partition, the sys- 
tem memory partition. 


The system memory partition is created when the kernel is initialized by 
kernelInit(), which is called by the root task, usrRoof( ), in usrConfig.c. The 
ID of the system memory partition is stored in the global variable 
memSysPartld, its declaration is included in memLib.h. 


The allocation of memory, using memPartAlloc() in the general case and 
nialloc() for the system memory partition, is done with a first-fit algorithm. 
Adjacent blocks of memory are coalesced when they are freed, using 
memPartFree( ) and free( ). 


ERROR OPTIONS 

Various debug options can be selected for each partition using 
memPartOptionsSet() and ntemOptionsSet(). Two kinds of errors are 
detected: attempts to allocate more memory than is available, and bad 
blocks found when memory is freed. In both cases, options can be selected 
for system actions to take place when the error is detected: (1) return the 
error status, (2) log an error message and return the error status, or (3) log an 
error message and suspend the calling task. 


One of the following options can be specified to determine the action to be 
taken when there is an attempt to anocate: more emery than is available in - 
the partition: - 4 


MEM_ALLOC_ERROR_ RETURN oe 
-. just return the error status to the calling: asset is to the cans “nsx 
MEM_ALLOC_ERROR_.LOG MSG ba 
+ log an error message and return the status to the ling task. 


MEM_ALLOC_ERROR_LOG_AND_SUSPEND | 

- log an error message and suspend the calling task. 
The following option can be specified to check every block freed to the parti- 
tion. If this option is specified, ntemtPartFree( ) and free() will make a con- 
sistency check of various pointers and values in the header of the block 
being freed. 


MEM_BLOCK CHECK 
- check each block freed. 
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One of the following options can be specified to determine the action to be 
taken when a bad block is detected when freed. These options apply only if 
the MEM_BLOCK_CHECK option is selected. 


MEM_BLOCK_ERROR_RETURN 
- just return the status to the calling task. 


MEM_BLOCK_ERROR_LOG MSG 
- log an error message and retum the status to the calling task. 


MEM_BLOCK_ERROR_LOG_AND_SUSPEND 
- log an error message and suspend the calling task. 


The default options when a partition is created are: 
MEM_ALLOC_ERROR_LOG MSG 
MEM_BLOCK_ CHECK 
MEM_BLOCK_ERROR_LOG_ AND_SUSPEND 


When setting options for a partition with memPartOptionsSet() or 
memOptionsSet(), use the logical OR operator between each specified 
option to construct the options parameter. For example: 


memPartOptionsSet (myPartId, MEM _ALLOC_ERROR_LOG MSG | 
MEM_BLOCK_CHECK | 
MEM _BLOCK_ERROR_LOG MSG); 


CAVEATS 


The routine malloc() always rounds up to a 4-byte boundary and there is an 
8-byte overhead for every block allocated. 


INCLUDE FILE 


memLib.h 


memPartCreate( ) - create a memory partition 


SYNOPSIS 


PART_ID mamPartCreate (pPool, poolSize) 
char *pPool; /* pointer to memory area */ 
unsigned poolSize; /* size in bytes */ | 


DESCRIPTION 


This routine creates a new memory partition containing the specified 
memory pool. It returns a partition ID which can then be passed to other 
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routines to manage the partition (i.e., to allocate and free memory blocks in 
the partition). Partitions can be created to manage any number of separate 
memory pools. 


NOTE 
The descriptor for the new partition is allocated out of the system memory 
partition (i.e., with malloc( )). 


RETURNS , 
The partition ID, or NULL if there is insufficient memory in the system 
memory partition for a new partition descriptor. 


SEE ALSO 
mem Lib 


NAME 
meniPartAddToPool{ ) - add memory to a memory partition 


SYNOPSIS 
STATUS memPartAddToPool (partId, pPool, poolSize) 
PART_ID  partid; /* partition to initialize */ 


char *pPool; /* pointer to memory block */ 
unsigned poolSize; /* block size in bytes */ 
DESCRIPTION 


This routine adds memory to a memory partition after the initial call to 
memPartCreate(). The memory added need not be contiguous with 
memory previously assigned to the partition. 


RETURNS seal 
OK or ERROR. 


SEE ALSO 
memLib, memPartCreate( ) 
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NAME 
memPartOptionsSet( ) - set the debug options for a memory partition 


SYNOPSIS 
STATUS memPartOptionsSet (partId, options) 
PART ID partId; /* partition for which to set option */ 
unsigned options; /* memory management options */ 


DESCRIPTION 

This routine sets the debug options for a specified memory partition. Two 
kinds of errors are detected: attempts to allocate more memory than is 
available, and bad blocks found when memory is freed. In both cases, the 
following options can be selected for actions to be taken when the error is 
detected: (1) return the error status, (2) log an error message and return the 
error status, or (3) log an error message and suspend the calling task. These 
options are discussed in detail in the library manual entry for memLib. 


RETURNS 
OK or ERROR. 


SEE ALSO 
memLib 


TOE 
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NAME a 
memPartAlloc( ) - allocate a block of. memory from a specified partition 


SYNOPSIS 
VOID *memPartAlloc (partId, nBytes) 
PART_ID partId; /* memory partition to allocate out of */ 
unsigned nBytes; /* number of bytes to allocate */ 


DESCRIPTION 
From a specified partition, this routine allocates a block of memory whose 
size is equal to or greater than nBytes. The partition must have been previ- 
ously initialized with menPartInit( ). 


RETURNS | 
A pointer to a block, or NULL if the call fails. 
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SEE ALSO 
mem Lib, memPartInit( ) 


NAME 
memPartRealloc( ) - reallocate a block of memory in a specified partition 


SYNOPSIS 
VOID *memPartRealloc (partId, pBlock, nBytes) 
PART_ID partId; /* partition ID */ 


char *pBlock; /* block to be reallocated */ 
unsigned nBytes; /* new block size in bytes */ 
DESCRIPTION 


This routine changes the size of a specified block and returns a pointer to the 
new block of memory. The contents that fit inside the new size (or old size 
if smaller) remain unchanged. 


RETURNS 
A pointer to the new block of memory, or NULL if the call fails. 


SEE ALSO 
memLib 


NAME : 
memPartFree( ) - free a block of memory in a specified partition 


SYNOPS!S : 

STATUS memPartFree (partId, pBlock) 
PART_ID partId; /* memory partition to add the block to */ 
char *pBlock; /* pointer to block of memory to be freed */ 


DESCRIPTION 
This routine takes a block of memory previously allocated with 
mentPartAlloc( ) and returns it to the partition’s free memory list. 
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RETURNS 
OK or ERROR if there is an invalid block. 


SEE ALSO 
memLib 


NAME 


memPartFindMax( ) - find the size of the largest available free block 


SYNOPSIS 
int memPartFindMax (partId) 
PART_ID partId; /* partition ID */ 


DESCRIPTION 
This routine searches for the largest block in the memory partition free list, 
and returns its size. 


RETURNS 
The size (in bytes) of the largest available block. 


SEE ALSO 
mem Lib 


NAME 


memPartShow() - show the partition blocks and statistics 


SYNOPSIS 
STATUS memPartShow (partId, type) 
PART ID partId; /* partition ID */ 
int type; /* 0 = statistics, 1 = statistics & list */ 


DESCRIPTION 
For a specified partition, this routine displays the total amount of free space 
in the partition, the number of blocks, the average block size, and the max- 
imum block size. It also shows the number of blocks currently allocated, 
and the average allocated block size. | 


In addition, if type is 1, this routine displays a list of all the blocks in the free 
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list of the specified partition. 
RETURNS 
OK or ERROR. 


SEE ALSO 
memLib, memShow{ ) 


NAME 
memAddToPool()- add memory to the system memory partition 


SYNOPSIS 
VOID memAddToPool (pPool, poolSize) 
char *pPool ; /* pointer to memory block */ 
unsigned poolSize; /* block size in bytes */ 


DESCRIPTION 
This routine adds memory to the system memory partition after the initial 
allocation of memory to the system memory partition. 


RETURNS 
N/A 


SEE ALSO 
memLib, memPartAddToPool( ) 


NAME 
memOptionsSet( ) - set the debug options for the system memory partition 


SYNOPSIS 
VOID memOptionsSet (options) 
unsigned options; /* options for system partition */ 


DESCRIPTION 
This routine sets the debug options for the system memory partition. Two 
kinds of errors are detected: attempts to allocate more memory than is 
available, and bad blocks found when memory is freed. In both cases, the 
following options can be selected for actions to be taken when the error is 
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detected: (1) return the error status, (2) log an error message and return the 
error status, or (3) log an error message and suspend the calling task. These 
options are discussed in detail in the library manual entry for memLib. 


RETURNS 
N/A 


SEE ALSO 
mem Lib, memPartOptionsSet( ) 


NAME 
malloc( ) - allocate a block of memory from the system memory partition 


SYNOPSIS 
VOID *malloc (nBytes) 
unsigned nBytes; /* number of bytes to allocate */ 


DESCRIPTION 
This routine allocates a block of memory from the free list whose size is 
equal to or greater than Bytes. 


RETURNS 
A pointer to the block, or NULL if the call fails. 


SEE ALSO 
memLib 


NAME 


calloc( ) - allocate space for an array 


SYNOPSIS 
VOID *calloc (elemNum, elemSize) | 
unsigned elemNum; /* number of elements */ 
unsigned elemSize; /* size of elements */ 


DESCRIPTION 
This routine allocates a block of memory for an array that contains elemNum 
elements of size elemSize. This space is initialized to zeros. 
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RETURNS 
A pointer to the block, or NULL if the calls fails. 


SEE ALSO 
memLib 


NAME 
realloc( ) - reallocate a block of memory 


SYNOPSIS 


VOID *realloc (pBlock, newSize) 
char *pBlock; /* block to be reallocated */ 
unsigned newSize; /* new block size */ 


DESCRIPTION 
This routine changes the size of a given block and returns a pointer to the 
new block of memory. The contents that fit inside the new size (or old size 
if smaller) remain unchanged. 


RETURNS 
A pointer to the new block of memory, or NULL if the call fails. 


SEE ALSO 
memLib 


NAME 
free() - free a block of memory 


SYNOPSIS 
STATUS free (pBlock) 
char *pBlock; /* pointer to block of memory to be freed */ 


DESCRIPTION | | 
This routine takes a block of memory previously allocated with malloc() or 
calloc() and returns it to the free memory pool. 


It is an error to free a block of memory that was not previously allocated. 
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RETURNS 
OK, or ERROR if the the block is invalid. 


SEE ALSO 
mem Lib 


NAME 


cfree( ) - free a block of memory 


SYNOPSIS 
STATUS cfree (pBlock) 
char *pBlock; /* pointer to block of memory to be freed */ 


DESCRIPTION 
This routine takes a block of memory previously allocated with calloc( ) and 


returns it to the free memory pool. 
It is an error to free a memory block that was not previously allocated. 


RETURNS 
OK, or ERROR if the the block is invalid. 


SEE ALSO 
memLib 


NAME 


memFindMax( ) - find the largest free block in the system memory partition 


SYNOPSIS 
int memFindMax () 


DESCRIPTION 
This routine searches for the largest block in the system memory partition 


free list and returns its size. 


RETURNS 
The size (in bytes) of the largest available block. 
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SEE ALSO - 
mem Lib, memPartFindMax( ) 
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NAME 
_ memShow()- show the system memory partition blocks and statistics 


SYNOPSIS 
VOID memShow (type) 
int type; 


DESCRIPTION 
This routine displays the total amount of free space in the system memory 
partition, the number of blocks, the average block size, and the maximum 
block size. It also shows the number of blocks currently allocated, and the 
average allocated block size. 


If type is 1, a list of all the blocks in the free list of the system partition is 


displayed. 
EXAMPLE 
-> memShow 1 
FREE LIST: 
num addr size 
1 Ox3feel8 16 
2 Ox3b1434 20 


3 0x4d188 2909400 


SUMMARY 3 ee ' 
status bytes blocks -ave block max block 


current 
free 2909436 3 969812 2909400 
alloc 969060 16102 60 - 
cumulative 
alloc 1143340 16365 69 - 
value = 12288 = 0x3000 = cFwd + 0x20 
RETURNS 
N/A 
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SEE ALSO 
mem Lib, mentPartShow( ) 
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NAME 
msgQLib - message queue library 


SYNOPSIS 
msgQCreate( ) - create and initialize a message queue 
msgQDelete( ) - delete a message queue 
msg(QSend()- send a message to a message queue 
msgQReceive( ) - receive a message from a message queue 
msgQNumMsgs( ) - get the number of messages queued to a message queue 
msgQInfoGet( ) - get information about a message queue 
msgQShow( ) - show information about a message queue 


MSG Q ID msgQCreate (maxMsgs, maxMsgLength, options) 
STATUS msgQDelete (msgQId) 

STATUS msgQSend (msgQId, buffer, nBytes, timeout, priority) 
int msgQReceive (msgQId, buffer, maxNBytes, timeout) 

int msgQNumMsgs (msgQId) 

STATUS msgQInfoGet (msgQId, pInfo) 

STATUS msgQShow (msgQId, level) 


DESCRIPTION 

In Vx960, message queues are the primary intertask communication 
mechanism within a single CPU. Message queues allow a variable number 
of messages (varying in length) to be queued in first-in-first-out order. Any 
task or interrupt service routine can send messages to a message queue. 
Any task can receive messages from a message queue. Multiple tasks can 
send to and receive from the same message queue. Full-duplex communica- 
tion between two tasks generally require two message queues, one for each 
direction. 


CREATING AND USING MESSAGE QUEUES 
A message queue is created with msgQCreate( ). Its parameters specify the 
maximum number of messages that will be allowed to be queued to that 
message queue and the maximum length in bytes of each message. Enough 
buffer space will be pre-allocated to accommodate the specified number of 
messages of specified length. 


A task or interrupt service routine sends a message to a message queue with 
msgQSend(). If no tasks are waiting for messages on the message queue, 
the message is simply added to the buffer of messages for that queue. If any 
tasks are already waiting to receive a message from the message queue, the 
message is immediately delivered to the first waiting task. 
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A task receives a message from a message queue with msgQReceive(). If 
any messages are already available in the message queue’s buffer, the first 
message is immediately dequeued and returned to the caller. If no messages 
are available, the calling task will block and be added to a queue of tasks 
waiting for messages. This queue of waiting tasks can be ordered either by 
task priority or FIFO, as specified in an option parameter when the queue is 
created. | 


TIMEOUTS 

Both msgQSend() and msgQkReceive() take timeout parameters. When 
sending a message, if no buffer space is available to queue the message, the 
timeout specifies how many ticks to wait for space to become available. 
When receiving a message, the timeout specifies how many ticks to wait if 
no message is immediately available. The value of the timeout parameter 
may have the special values of NO_WAIT (0) meaning to always return 
immediately or WAIT_FOREVER (-1) meaning to never time out. 


URGENT MESSAGES : 
The msgQSend() function allows the priority of a message to be specified as 
either normal (MSG_PRI_ NORMAL) or urgent (MSG_PRI_URGENT). Nor- 
mal priority messages are added to the tail of the list of queued messages, 
while urgent priority messages are added to the head of the list. 


SEE ALSO 
pipeDrv, Programmer's Guide: Basic OS 


NAME 
msgQCreate( ) - create and initialize a message queue 
SYNOPSIS | 
MSG Q ID msgQCreate (maxMsgs, maxMsgLength, options) 
int maxMsgs; /* max messages that can be queued */ 
int maxMsgLength; /* max bytes in a message */ 
int options; /* message queue options */ 
DESCRIPTION 


This routine creates a message queue capable of holding up to maxMsgs 
messages, each of up to maxMsgLength bytes long.. It returns a message 
queue ID used to identify the created message queue in all subsequent calls 
to routines in this library. The queue can be created with the following 


options: 
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MSG Q. FIFO - queue pended tasks in FIFO order. 

MSG_Q PRIORITY - queue pended tasks in priority order. 
RETURNS 

MSG Q _ID, or NULL if error. 


ERRNO 
S_memLib_NOT_ENOUGH_MEMORY 


“unable to allocate memory for message queue and message buffers. 


S_intLib_NOT_ISR_CALLABLE 
called from an interrupt service routine. 


SEE ALSO 
msgQLib 


NAME 


msgQDelete() - delete a message queue 


SYNOPSIS 
STATUS msgQDelete (msgQId) 
MSG Q ID msgQId; /* message queue to delete */ 


DESCRIPTION | 
This. routine deletes a message: queue. Any~task blocked on either a 
msgQSend() or msgQReceive(’ )-will be unblocked ‘and receive an error from 
the call with errno set:to S:bjLib.OBJECT_ DELETED. sic ns 
msgQId will no _ be a-valid message queue ID. 


OK, or ERROR. ee a a Te 


ERRNO ae 
S_objLib_OBJ ID ERROR 
the msgQld is invalid. 
S_intLib_ NOT_ISR_CALLABLE 
called from an interrupt service routine. 


SEE ALSO 
msgQLib 


1-232 Intel | | Rev: 29 Aug 91 


seers 


ese 


San SSN 


Maes ES Sere SSeSSaitieeseceset eee KES 


Si Neurataraseterererermetecetaresenetene’ sorsteteratorsectaretcteraretetieresonens 


NAME 
msgQSend() - send a message to a message queue 


SYNOPSIS 
STATUS msqQSend (msgQId, buffer, nBytes, timeout, priority) 
MSG Q ID msgQId; /* message queue on which to send */ 
char * buf fer; /* message to send */ 


UINT nBytes; /* length of message */ 

int timeout; /* ticks to wait */ 

int priority; /* MSG _PRI_NORMAL or MSG _PRI_URGENT */ 
DESCRIPTION 


This routine sends the message in buffer of length nBytes to the message 
queue msgQld. If any tasks are already waiting to receive messages on the 
queue, the message will immediately be delivered to the first waiting task. 
If no task is waiting to receive messages, the message is saved in the mes- 
sage queue. 


The timeout parameter specifies the number of ticks to wait for free space if 
the message queue is full. timeout can have the special value NO_WAIT that 
indicates msgQSend() will return immediately even if the message has not 
been sent. Another value for timeout is WAIT_FOREVER that indicates that 
msg(QSend() will never timeout. 


The priority parameter specifies the priority.of the.message being sent. Nor- 

_mal priority messages (MSG_PRI_NORMALE):are-added+o the tail of the list 
of queued messages. Urgent iain Lapel a PRE: evRGeN) are 
added to the head of the list. Aisne : 


USE BY INTERRUPT SERVICE ROUTINES = 849 trite? Sh 
This routine can be called by interruptserwice: routines as gwell as by tasks. 
This is one of the primary means of2cormunication between an interrupt 
service routine and a task. When called-from.‘an: pail a service routine, 
timeout must be specified as NO_WAIT. ny 


RETURNS 
OK, or ERROR. 


ERRNO 
S_objLib_OBJ ID_ERROR 
the msgQld is invalid. 


S_objLib_ OBJ DELETED 
the message queue was deleted while waiting to a send message. 
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S_objLib_OBJ_ UNAVAILABLE 

timeout is set to NO_WAIT and the queue is full. 
S objLib_OBJ TIMEOUT 

the queue is full for timeout ticks. 


S_msgQLib INVALID MSG LENGTH 
nBytes is larger than the maxMsgLength set for the message queue. 


S_msgQLib_ NON_ZERO_TIMEOUT_AT_INT_LEVEL 
called from an ISR with timeout not set to NO_WAIT. 


SEE ALSO 
msgQLib 


NAME 
msgQReceive() - receive a message from a message queue 
SYNOPSIS 
int msgQReceive (msgQId, buffer, maxNBytes, timeout) 
MSG Q ID msgQId; /* message queue from which to receive*/ 
char * buffer; /* buffer to receive message */ 
UINT maxNBytes; /* length of buffer */ 
int timeout; /* ticks to wait */ 
DESCRIPTION 


This routine receives a message from the message queue msgQId. The 
received message is copied into the specified buffer, which is maxNBytes in 
length. If the message is longer than maxNBytes, the remainder of the mes- 
sage is discarded (no error indication is returned). os 


The timeout parameter specifies the number of ticks to wait for a message to 
be sent to the queue, if no message is available when msgQReceive( ) is 
called. timeout can have the special value NO WAIT that indicates 
msgQReceive() will return immediately even if a message is available. 
Another value for timeout is WAIT_FOREVER that indicates that 
msgQReceive() will never timeout. 


This routine must not be called by interrupt service routines. 


RETURNS 
The number of bytes copied to buffer, or ERROR. 
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ERRNO 
S_objLib_OBJ ID_ERP.OR 
the msgQlId is invalid. 
S_objLib_OBJ DELETED 
the message queue was deleted while waiting to receive a message. 
S_objLib OBJ UNAVAILABLE 
timeout is set to NO_WAIT and no messages are available. 
S_objLib_ OBJ TIMEOUT 
no messages were received in timeout ticks. 


S_msgQLib_ INVALID _MSG_ LENGTH 
nBytes is less than 0. 


SEE ALSO 
msgQLib 


NAME 
msgQNumMsgs() - get the number of messages queued to a message queue 


SYNOPSIS 
dint msgQNumMsgs (msgQId) 
MSG 9 ID msgQId; /* message queus to examine */ 
DESCRIPTION 
This routine returns the number of messages currently queued to a specified 
message queue. 


RETURNS 
The number of messages queued, or ERROR. 


ERRNO | 
S_objLib_ OBJ ID ERROR 
the msgQId is invalid. 


SEE ALSO 
msgQLib 
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NAME 
msgQInfoGet( ) - get information about a message queue 


SYNOPSIS 
STATUS msgQInfoGet (msgQId, pInfo) 
MSG _Q ID msgQId; /* massage queue to query */ 
MSG _Q INFO * pInfo; /* where to return msg info */ 


DESCRIPTION 
This routine gets information about the state and contents of a message 
queue. The parameter plnfo is a pointer to a structure of type MSG_Q_ INFO 
defined in msgQLib.h as follows: 


typedef struct /* MSG Q INFO * 


{ 

int numMsgs; /* OUT: number of messages queued * 

int numTfasks; /* OUT: number of tasks waiting on msg q * 
int sendTimeouts; /* OUT: count of send timeouts * 

int recvTimeouts; /* OUT: count of receive timeouts * 

int options; /* OUT: options with which msg q was created * 
int maxMsgs; /* OUT: max messages that can be queued * 

int maxMsgLength; /* OUT: max byte length of each message * 
int taskIdListMax; /* IN: max tasks to fill in taskIdList * 


int * taskIdList; /* PTR: array~of task: IDs waiting on msg q * 


int msgListMax; /* IN: max msgs:to fill.in msg lists * 
char ** msgPtrList; /* PIR« arrayjof<msg_ptrs queued to bade q * 
int * msgLenList; /* PTR:* “array Of Lengths‘ of-nsgs *- ans 
} MSG_Q INFO; > Hah Goa. 


If a message queue is empty,:there-*may be tasks-blocked on receiving. If a 
message queue is full, there may be oe blocked on sending. This can be 
determined as follows: _ 


- If numMsgs is 0, then numTasks indicates the number of tasks blocked on 
receiving. 


- If numMsgs is equal to maxMsgs, then numlasks is the number of tasks 
blocked on sending. 


- If numMsgs is greater than 0 but less than maxMsgs, numTasks willbe 0. 
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A list of pointers to the messages queued and their lengths can be obtained 
by setting msgPtrList and msgLenList to the addresses of arrays to receive the 
respective lists, and setting msgListMax to the maximum number of ele- 
ments in those arrays. If either list pointer is NULL, no data will be returned 
for that array. 


No more than msgListMax message pointers and lengths are returned, 
although numMsgs will always be returned with the actual number of mes- 
‘sages queued. 


For example, if the caller supplies a msgPtrList and msgLenList with room for 
10 messages and sets msgListMax to 10, but there are 20 messages queued, 
then the pointers and lengths of the first 10 messages in the queue are 
returned in msgPtrList and msgLenList, but numMsgs will be returned with 
the value 20. 


A list of the task IDs of tasks blocked on the message queue can be obtained 
by setting taskIdList to the address of an array to receive the list, and setting 
taskIdListMax to the maximum number of elements in that array. If taskIdList 
is NULL, then no task IDs are returned. No more than taskIdListMax task 
IDs are returned, although numTasks-will:always be returned with the actual 
number of tasks blocked. 


For example, if the caller supplies a taskIdList with room for 10 task IDs and 
sets taskIdListMax to 10, but there are 20 tasks blocked on the message 
queue, then the IDs of the first 10 tasks in the blocked queue will be returned 
in taskIdList, but numTasks will be returned with the value 20. 


Note that the tasks returned in taskIdList. may -be blocked for either make or. 


‘receive. As noted above this can be: determined: -by-examining numMsgs::° 


The variables sendTimeouts and recvTimeoutsake:the-counts: Of the’ number of: : -:: 


times msgQSend() and rrr svégpectiVely:creturned:: -with-a ° 
timeout. 


The variables options, maxMsgs, and: ra a are = the: parameters with 
which the message queue was created: ee 


WARNING | 

The information returned by this routine is not static:and may be obsolete 
by the time it is examined. In particular, the lists of task IDs and/or message 
pointers may no longer be valid. However, the information is obtained 
atomically, thus it will be an accurate snapshot of the state of the message 
queue at the time of the call. This information is generally used for debug- 


ging purposes only. 
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WARNING 
The current implementation of this routine locks out interrupts while 
obtaining the information. This can compromise the overall interrupt 
latency of the system. Generally this routine is used for debugging pur- 
poses only. 


RETURNS 
OK, or ERROR. 


ERRNO | 
S_objLib_ OBJ _ID_ERROR 
the msgQld is invalid. 


SEE ALSO 
msgQLib 


NAME 


nisgQShow( ) - show information about a message queue 


SYNOPSIS 
STATUS msgQShow (msgQId, level) 
MSG Q ID msgQId; /* message queue to display */ 


int level; /* 0 = summary, 1 = details */ 
DESCRIPTION 
This routine displays the state and optionally the contents of a message 
queue. 


A summary of the state of the message queue is displayed as follows: 


Message queue id 0x12345678: 
PRIORITY Task queuing 
100 Message length max (bytes) 

10 Messages max : 
QO Messages queued 
QO Receivers blocked 

12345678 Send timeouts 

12345678 Receive timeouts 


If level is 1, then more detailed information will be displayed. If messages 
are queued, they will be displayed as follows: 
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Messages queued: 
# address length value 
1 0x123eb204 4 0x00000001 0x12345678 


If tasks are blocked on the queue, they will be displayed as follows: 


Receivers blocked: 
0x3e134 (tExcTask) 


SEE ALSO 
msgQLib 
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NAME 
netLib - network interface library 


SYNOPSIS 
netLibInit{ ) - initialize the network packyee 
netTask( ) - network task entry point 


STATUS netLibInit () 
VOID netTask () 


DESCRIPTION 
This module contains the network task that runs low-level network interface 
routines in a task context. The network task executes and removes routines 
that were added to the job queue. This facility is used by network interfaces 
in order to have interrupt-level processing done at task level. 


The routine netHelp( ) in usrLib displays a summary of the network facili- 
ties available from the Vx960 shell. 


SEE ALSO 
routeLib, hostLib, netDrv, netHelp(), Programmer's Guide: Network 


NAME 
netLibInit( ) - initialize the network package 


SYNOPSIS 
STATUS netLibInit () 


DESCRIPTION 
This routine installs the socket driver, creates the network task job queue, 
and spawns the network task netTask(). It should be called once to initial- 
ize the network. If INCLUDE_NETWORK is defined in configAILh, this is 
done by usrRoot( ) in usrConfig.c. 


RETURNS 
OK, or ERROR if network support cannot be initialized. 


SEE ALSO 
netLib, usrConfig 
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NAME 
netTask( ) - network task entry point 


SYNOPSIS 
VOID netTask () 


DESCRIPTION 
This routine is the Vx960 network support task. Most of the Vx960 network 
runs in this task’s context. 


Note: To prevent an application task from monopolizing the CPU if it is in 
an infinite loop or is never blocked, the priority of netTask() relative to an 
application may need to be adjusted. Network communication may be lost 
if netTask() is “starved” of CPU time. The default task priority of 
netTask( ) is 50. Use taskPrioritySet({ ) to change the priority of a task. 


This task is spawned by netLiblInit{ ). 


RETURNS 
N/A 


SEE ALSO 
netLib 
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NAME 
netShow - network related information display routines 


SYNOPSIS 
_ ifShow() - display the attached network interfaces 
icmpstatShow/( ) - display statistics for ICMP 
inetstatShow( ) - display all active connections for Internet protocol sockets 
ipstatShow( ) - display IP statistics 
mbufShow( ) - report mbuf statistics 
netShow!Init( ) - initialize network show routines 
tcpstatShow ) - display all statistics for the TCP protocol 
udpstatShow ) - display statistics for the UDP protocol 
arptabShow( ) - display the known ARP entries 


VOID ifsghow (ifName) 
VOID iompstatShow () 
VOID inetstatShow () 
VOID ipstatShow (zero) 
VOID mbufShow () 
VOID netShowInit () ... 
VOID tcpstatShow () 
VOID udpetatShow () 
VOID arptabShow () 
DESCRIPTION 
This library provides routines to show various network-related statistics, 


such as configuration: bbe noaaa ‘for’ network interfaces, protocol statistics, | 
socket statistics, arnd-so-forth.:. = zr 


SEE ALSO oe 
sei Propane! Guide: ‘Network routeShow,. hostShow 


NAME 


ifShow( ) - display the attached network interfaces 


SYNOPSIS 
VOID ifshow (ifName) 
char ‘*ifNeme; /* name of the interface to show */ 
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DESCRIPTION 


This routine displays the attached network interfaces for debugging and 
diagnostic purposes. If ifName is given, only the interfaces belonging to that 
group are displayed. If ifName is omitted, all attached interfaces are 
displayed. 


For each interface selected, the Internet address, point-to-point peer address 


_ (if using SLIP), broadcast address, netmask, subnet mask, Ethernet address, 


route metric, maximum transfer unit, number of packets sent and received 
on this interface, number of input and output errors, and flags (e.g., loop- 
back, point-to-point, broadcast, promiscuous, arp, running, debug) are 
shown. 


Note that routeShow can also be used to determine the number of interfaces. 


EXAMPLE 


The following call displays all interfaces whose names begin with “‘ei’’, (e.g., 
“ei0”, “eil”, “ei2”, etc.): 


-> ifghow "ei" 


The following call displays just the interface “ei0”’: 


-> ifsShow “eid” 


RETURNS 


N/A 


SEE ALSO 7 


netShow, routeShow( ), ifLib, Programmer's Guide: Network 


NAME 


icmpstatShow( ) - display statistics. for ICMP 


SYNOPSIS 


VOID icmpstatShow () 


DESCRIPTION 


This routine displays statistics for the ICMP protocol. 


RETURNS 


N/A 
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SEE ALSO 
netShow, Programmer's Guide: Network 


MAME 


inetstatShow/( ) - display all active connections for Internet protocol sockets 


SYNOPSIS 
VOID inetstatsShow () 


DESCRIPTION | 
This routine displays a list of all active Internet protocol sockets in a format 
similar to the UNIX netstat command. 


RETURNS 
N/A 


SEE ALSO 
netShow, Programmer's Guide: Network 


NAME : 
ipstatShow( ) - display IP statistics : 


SYNOPSIS 
VOID ipstatShow (zero) \ 
BOOL sero; /* TRUE = reset statistics to 0 */ ; 


DESCRIPTION 
This routine displays detailed statistics for the IP protocol. < 


RETURNS 
N/A 


SEE ALSO 
netShow 
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NAME 
mbufShow( ) - report mbuf statistics 


SYNOPSIS 
VOID mbufshow () 


DESCRIPTION 
This routine displays the distribution of mbufs in the network. 


RETURNS 
N/A 


SEE ALSO 
netShow 


NAME 
netShow!Init( ) - initialize network show routines 
SYNOPSIS 
VOID netShowiInit () 
DESCRIPTION 
This routine links the network show routines.into the Vx960 system. These 
routines “ are included ecm, aw ‘by defining 
INCLUDE_NETWORK: SHOW in configAILh. - . ee 
RETURNS 
N/A 
SEE ALSO 
netShow 
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NAME 


tcpstatShow( ) - display all statistics for the TCP protocol 


SYNOPSIS 
VOID tcpstatshow () 


DESCRIPTION 
This routine displays detailed statistics for the TCP protocol. 


RETURNS 
N/A 


SEE ALSO 
netShow, Programmer's Guide: Network 


NAME 


udpstatShow( ) - display statistics for the UDP protocol 


SYNOPSIS 
VOID udpstatShow () 


DESCRIPTION | | 
This routine displays statistics for the UDP protocol. 


RETURNS 
N/A 


SEE ALSO : : 
netShow . 


NAME 


arptabShow( ) - display the known ARP entries 
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SYNOPSIS 
VOID arptab6how () 


DESCRIPTION | | 
This routine displays current IP-to-Ethernet mappings in the ARP table. 


RETURNS 
N/A 


SEE ALSO 
netShow 
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NAME 
nfsLib - Network File System library 


SYNOPSIS 
nfsHelp({ ) - display the NFS help menu 
nfsExportShow( ) - display the exported file systems of a remote host 
nfsAuthUnixPrompt{ ) - modify the NFS UNIX authentication parameters 
nfsAuthUnixShou ) - display the NFS UNIX authentication parameters 
nfsAuthUnixSet() - set the NFS UNIX authentication parameters 
nfsAuthUnixGet, ) - get the NFS UNIX authentication parameters 
nfsIdSet() - set the ID number of the NFS UNIX authentication parameters 


VOID nfsHelp () 

STATUS nfsExportShow (hostName) 

VOID nfsAuthUnixPrompt () 

VOID nfsAuthUnixShow () 

VOID nfsAuthUnixSet (machname, uid, gid, ngids, . gids) 
VOID nfsAuthUnixGet (machname, pUid, pGid, pigids, gids) 
VOID nfsidset (uid) 


DESCRIPTION 
This library provides the client side of services for Network File System 
(NFS) devices. Most routines in this library should not be called by users, 
but rather by device drivers. The driver is responsible for keeping track of 
file pointers, mounted disks, and cached buffers. This library uses Remote 
Procedure Calls (RPC) to make the NFS calls. 


Vx960 is delivered with NFS enabled. NFS is enabled by defining the. con- 
stant INCLUDE_NFS in the | Vx960° configuration header file: 
config/all/configAILh: 9 - | ‘s: : 


idefine INCLUDE FS 


In the same file, the parameters NFS_USER_ID. and NFS.GROUP_ID should’: * 


be defined to set the default user ID and group ID. at system start-up. ‘See 
the “Network” chapter in the Programmer's Guide for information on creating 
NFS devices. a: 


NFS USER IDENTIFICATION 
NES is built on top of RPC and uses a type of RPC authentication‘known as 
AUTH_UNIX, which is passed onto the NFS server with every NFS request. 
AUTH_UNIX is a structure that contains necessary information for NFS, 
including the user ID number and a list of group IDs that the user belongs 
to. On UNIX systems, a user ID is specified in the file /etc/passwd. The list 
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of groups that a user belongs to is specified in the file /etc/group. 


To change the default authentication parameters, — use 
nfsAuthUnixPrompt{ ). To change just the AUTH_UNIX ID, use nfsIdSet(). 
Usually, only the user ID needs to be changed to indicate a new NFS user. 


TASK STACK SIZE 
In previous versions of Vx960, the recursive nature of the underlying XDR 
(eXternal Data Representation) routines for RPC required large task stacks 
(> 7000 bytes). In Vx960 5.0, these stack requirements have been reduced 
considerably. Normal use of NFS requires no more than 2000 bytes of stack. 


INCLUDE FILE 
nfsLib.h 


SEE ALSO 
rpcLib, ioLib, nfsDrv, Programmer's Guide: Network 


NAME 
nfsHelp( ) - eine the NES help menu 
SYNOPSIS 
VOID nfsKelp () 
DESCRIPTION 
This routine. displace a nace ‘of NFS: facilities typically::called ‘from the 
shell: 
nfsHelp seo . Print this list 
netBelp | 2. BSto.. Print general network baie list... 


nfsMount “host”, “filesysten*{7,"devname" ] «Create device with  . -= 
file system/directory from host- =: 


nfsUnmount “devname" - =2-= Remove an MFS device 

nfsAuthUnixsShow A iti, See vee Print current UNIX authentication 

nfsAuthUnixPrompt | aoe Prompt. for UNIX authentication 

nfsIdget id Set dues eae UNIX authentication 

nf sDevShow arity DPrint list of mFS devices 

nfsExportShow "host" “27 -print a list of FB file systems which 
are exported on the specified host 

mkdir “dirname” Create directory 

m “file” Remove file 
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EXAMPLE: -> hostAdd “wrs", "90.0.0.2" 
-> nfsMount wre", "/disk0/path/sydir", " fmydix/" 


-> od "/mydir/" 

-> nfsaAuthUnixPrompt /* €111 in user ID, etc. * 

-> ls /* list /diskO/path/mydir * 
-> copy < foo /* copy foo to standard out * 
-> ld < foo.o /* load object module foo.o * 
-> nfsUnmount “/mydir/" /* remove NFS device /mydir/ * 

SEE ALSO 
nfsLib 


NAME 
nfsExportShow( ) - display the exported file systems of a remote host 


SYNOPSIS 
_* STATUS nfsExportShow (hostKName) 
char ‘*hostName; /* host machine for which to show exports */ 


DESCRIPTION 
This routine displays the file systems of a ‘Specified host and the groups that 
are allowed to mount them. 


EXAMPLE 
-> nfskxportShow “wrs" 
/a0 _ ptaff 
/dl staff eng 
a2 eng 
/d3 : 
value = 0 = 0x0 
RETURNS 
OK or ERROR. 
SEE ALSO 
nfsLib 
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NAME 
nfsAuthUnixPrompt( ) - modify the NFS UNIX authentication parameters 


SYNOPSIS 
VOID nfsAuthUnixPrompt () 


DESCRIPTION 
This routine allows UNIX authentication parameters to be changed from the 
shell. The user is prompted for each parameter, which can be changed by 
entering the new value next to the current one. 


EXAMPLE 


-> nfsAuthUnixPrompt 
machine name: yuba 


user ID: | 2001 128 
group ID: 100 
num of groups: 1 3 
group #1: 100 100 
group #2: 0 120 
group #3: 0 200 
value = 3 = 0x3 
SEE ALSO 
nfsLib, snfsAuthUnixGet(), xnfsAuthUnixSet(), nfsAuthUnixShow( ), 
nfsIdSet( ) 


NAME | 
nfsAuthUnixShow( ) - display the NFS UNIX authentication parameters 


SYNOPSIS | 
VOID nfsAuthUnixShow () 


DESCRIPTION | 
This routine displays the parameters set by nfsAuthUnixSet() or 
nfsAuthUnixPrompt ). | 


EXAMPLE 
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user ID = 2001 
group ID = 100 
group [0] = 100 
value = 1 = Oxl 


SEE ALSO 
nfsLib, nfsAuthUnixGet(), nfsAuthUnixSet(), nfsAuthUnixPrompt(), 
nfsIdSet( ) 


NAME 
nfsAuthUnixSet( ) - set the NFS UNIX authentication parameters 
SYNOPSIS 
VOID nfsAuthUnixZet (machname, uid, gid, ngids, aup_ gids) 
char ‘*machname; /* host machine «/ 
int uid; ... /* user ID «/ 
int gid; /* group ID «/ 
int ngids; «<::. /* number of group IDs */ 
int *aup gids; /* array of group IDs */ 
DESCRIPTION | 
This routine sets’ ‘UNIX: authentication parameters. It is initially called in 
usrNetInit( i in usrConfig. 
SEE ALSO 
nfsLib, inane ater ane ptt y nfsIdSet(), nfsAuthUnixGet( ), 
nfsAuthUnixShou():* : 


2 
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NAME 
nfsAuthUnixGet( )-.get the NFS UNIX authentication parameters 
SYNOPSIS 
VOID nfsAuthUnixGet (machname, puid, pGid, piigids, gids) 
char ‘*machname; /* where to store host machine «/ 
int *puid; /* where to store user ID «/ 
int ‘*pGid; /* where to store group ID «/ 
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int ‘“pNgids; /* where to store number of group IDs */ 
int ‘gids; /* where to store array of group IDs */ 


DESCRIPTION 
This routine gets the previously set UNIX authentication values. 


SEE ALSO 
nfsLib, nfsAuthUnixPrompt(), nfsAuthUnixSet(), nfsAuthUnixShow( ), 
nfsIdSet( ) 


NAME 
nfsIdSet() - set the ID number of the NFS UNIX authentication parameters 


SYNOPSIS 
VOID nfsIdset (uid) 
int uid; /* user ID on host machine */ 


DESCRIPTION 
This routine sets only the UNIX authentication user ID number. For most 
NFS permission needs, only the user ID needs to be changed. Set uid to the 
user ID on the NFS server. 


SEE ALSO 
nfsLib, nfsAuthUnixPrompt(), nfsAuthUnixGet{), nfsAuthUnixSet( ), 
nfsAuthUnixShow( ) | | 
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NAME 


rawFsLib - raw block device file system library 


SYNOPSIS 
rawFsDevInit( ) - associate a block device with raw volume functions 
rawFsInit( ) - prepare to use the raw volume library 
rawFsModeChange( ) - modify mode of raw device volume 
rawFsReadyChange( ) - notify rawFsLib of a change in ready status 
rawFsVolUnmount{ ) - disable a raw device volume 


RAN _VOL DESC ‘*rawFsDeviInit (volName, pBlkDev) 
STATUS rax¥sInit (maxFiles) 
VOID raw’ sModeChange (vdptr, newtode) 


VOID rawFsReadyChange (vdptr) 
STATUS raw’ sVolUnmount (vdptr) 


DESCRIPTION | 
This library provides basic services for disk devices that do not use a stan- 
dard file or directory structure. The disk volume is treated much like a large 
file. Portions of it may be read, written, or the current position within the 
disk may be changed. However, there is no high-level organization of ‘the 
disk into files or directories. | 


USING THIS LIBRARY 
The various functions provided by the Vx960 rawFs file system may be 
separated into three broad groups:. general initialization, device initializa- 
tion, and file system operation. 


The rawFsInit( ) function is the principal initialization function; it foes se penries 
be called once, regardiess‘of ‘how many TawFs:dévices will be used: :te=3 will he ue- 


A separate rawFs function: is -used for: device :initialization.' For each: rawFso7. 
device, rawFsDevInit( ) must be-called:to install the device. © re fe erice, 


Lastly, several functions are provided to inform the file system of changeé$-iny :.<: 1 
the system environment. The rawFsModeChange() call. may: be: used? toil may 
modify the readability’. or writability - of a particular dévice. . The:.':: «: 
rawFsReadyChange( ) function is used to inform the file system that a disk. 
may have been swapped, and that the next disk operation should first 
remount the disk. Finally, the rawFsVolUnmount{ ) function informs the file | 
system that a particular device should be synchronized and unmounted, 
generally in preparation for a disk change. 


More detailed information on all of these functions is discussed in the 
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following sections. 


INITIAUZATION 
Before any other routines in rawFsLib can be used, the rawFsInit( ) routine 
must be called to initialize the library. This call specifies the maximum 
number of raw device file descriptors that can be open simultaneously and 
allocates memory for that many raw file descriptors. Any attempt to open 
more raw device file descriptors than the specified maximum will result in 
errors from open( ) or creat{( ). 


During the rawFsInit{ ) call, the raw device library is installed as a driver in 
the I/O system driver table. The driver number associated with it is then 
placed ina global variable, rawFsDruNum. 


To enable this initialization, define INCLUDE_RAWFS in configAII.h; 
rawFsInit{) will then be called from the root task, usrRoot(), in 
usrConfig.c. 


DEFINING A RAW DEVICE 
To use this library for a particular device, the device structure used by the 
device driver must contain, as the very first item, a block device description 
structure (BLK_DEV). This must be _ initialized before--«calling” 
rawFsDevInit(). In the BLK DEV structure, the driver includes the 
addresses of five routines it must supply: one that reads ‘one‘or:more-blocks; . __ 
one that writes one or more blocks, one that performs [/O:controk {ioctl()):. . 
on the device, one that checks the status of the the:device,and ‘one that ~~ 
resets the device. The BLK_DEV structure also contains ‘fields that describe : 
the physical configuration of the device. See the “I/O System’ chapter in 
the Programmer's Guide for more information on defining block-devicesi2iie:: e200: 


Am 


The rawFsDevInit( ) routine is used to associate a‘device. with: the‘rawFsLib:=°- + - 
functions. The volName parameter expected by rawFsDevInit(}‘isa-pointet vy raw: 
to a name string, to be used to identify the device. This.will serveasythe: covice. 
pathname for I/O operations which operate on the: device: ‘Thistiame wille on ite 
appear in the I/O system device table, whiy may: Pe ciepyca ts irsing the’c: “ny 
iosDevShow( ) routine. | 

The pBlkDev parameter that rawFsDevInit{ ). Siiaiaialietteals ‘to thei > - 5 
BLK_DEV structure describing the device and contains the addresses ofthe: °°» 
required driver functions. The syntax of the rawFsDevInit(): routine isias- : 
follows: 


Yew? sDevinit (volMame, pBlkDev) ; | 
char ‘*volName; /* name to be used for volume  * 
BIX DEV ‘“palkDev; /* pointer to device descriptor * 


Unlike the Vx960 DOS and RT-11 file systems, raw volumes do not require 
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an FIODISKINIT ioctl() function to initialize volume structures. (Such an 
toctl( ) call can be made for a raw volume, but it has no effect.) As a result, 
there is no “‘make file system’ routine for raw volumes (for comparison, see 
the dosFsMkfs() and rt11Mkfs( ) routines). 


After rawFsDevInit({ ) has been called, when rawFsLib receives a request 
from the I/O system, it calls the device driver routines (whose addresses 
were passed in the BLK_DEV structure) to access the device. 


MULTIPLE LOGICAL DEVICES 

The block number passed to the block read and write routines is an absolute 
number, starting from block 0 at the beginning of the device. If desired, the 
driver may add an offset from the beginning of the physical device before 
the start of the logical device. This would normally be done by keeping an 
offset parameter in the driver's device-specific structure, and adding the 
proper number of blocks to the block number passed to the read and write 
routines. See the ramDrv manual entry for an example. 


UNMOUNTING VOLUMES (CHANGING DISKS) 
A disk should be unmounted before it is removed. When unmounted, any 
modified data that has not been written to the disk will be written out. A 
disk may be unmounted by either calling rawFsVolUnmount{ ) directly or 
calling toctl() with a FFODISKCHANGE function code. 


There may be open file descriptors to a raw device volume when it is 
unmounted. If this is the case, those file descriptors will be marked as 
obsolete. Any attempts to use them for further I/O operations will return 
an S_rawFsLib_FD_OBSOLETE error. To free such file descriptors, use the 
close() call, as usual. This will successfully free the descriptor, but will still _ 
return S_rawFsLib_FD OBSOLETE. 


SYNCHRONIZING. VOLUMES 
. A disk should be “synchronized” b before is is unmounted. To synchronize a 
” disk means to Write-out.all:buffered data (the write buffers associated with 
open file descriptors),'so that the disk is updated. It may or may not be 
necessary to explicitly synchronize a disk, oe on how (or if) the 
driver issues the rawFsVolUnmount{ ) call. , 


When rawFsVolUnmount{ ) is called, an attempt will be made to neice 
ize the device before unmounting. However, if the rawFsVolUnmount{ ) call 
is made by a driver in response to a disk being removed, it is obviously too 
late to synchronize. Therefore, a separate ioctl() call specifying the 
FIOSYNC function should be made before the disk is removed. (This could 
be done in response to an operator command.) 


If the disk will still be present and writable when rawFsVolUnmount{ ) is 
called, it is not necessary to explicitly synchronize the disk first. In all other 
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circumstances, failure to synchronize the volume before unmounting may 
result in lost data. 


iOCTL FUNCTIONS 
The Vx960 raw block device file system supports the following ioctl( ) func- 
tions. The functions listed are defined in the header ioLib.h. 


FIODISKFORMAT 
- Formats the entire disk with appropriate hardware track 
and sector marks. No file system is initialized on the disk 
by this request. Note that this is a driver-provided func- 
tion: 
fd = open (“DEV1:", WRITE); 
status = ioctl (fd, FIODISKFORMAT) ; 


FIODISKINIT - Initializes a raw file system on the disk volume. Since 
there are no file system structures, this functions performs 
no action. It is provided only for compatibility with other 
Vx960 file systems. 


FIODISKCHANGE 
- Announces a media change. It performs the same func- 
tion as rawFsReadyChange(). This function may be 
called from interrupt level: 


status = ioctl (fd, FIODISKCHARGE); 


FIOUNMOUNT 
- Unmounts a disk volume. It performs the same function 
as rawFsVolUnmount( ). This function must not be called 
from interrupt level: 


status = ioctl (fd, FIOUMOUNT); 


FIOGETNAME- Gets the file name of the fd and copies it to the buffer 
nameBuf. 


status = ioctl (fd, FIOGETINAME, GnameBuf); 
FIOSEEK - Sets the current byte offset:on the disk to the position 
specified by newOffset: 


 gtatus = foctl (fd, FIOGEEK, newOffset); 


FIOWHERE~ - Returns the current byte position from the start of the 
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device for the specified file descriptor. This is the byte 
offset of the next byte to be read or written. It takes no 
additional argument: 


position = ioctl (fd, FIOMMERE); 


FIOFLUSH - Writes all modified file descriptor buffers to the physical 
device. 


status = ioctl (fd, FIOFLUSH); 


FIOSYNC - Performs the same function as FIOFLUSH. 


FIONREAD ~~ - Copies to unreadCount the number of bytes from the 
current file position to the end of the device: 


status = ioctl (fd, FIOMREAD, GunreadCount); 


INCLUDE FILE 
rawFsLib.h 


SEE ALSO 
ioLib, iosLib, dosFsLib, rt11FsLib, ramDrv, 
Programmer's Guide: I/O System, Local File Systems 


NAME 
rawFsDevInit( - associate a block device with raw.volume functions °2°. "2: 
SYNOPSIS = shee 3 | 
RAW _VOL_DESC *rewfsDevinit (volName, patios) i ty ee ey 
char *vyolMame;' /* volume name :*/- ; # 
BLK DEV ‘*pBlkDev; /* porater: to block device. info: “/ ot eye ap 
DESCRIPTION 


This routine fakes a block device created by a device driver and defines it as 
a raw file system volume. As a result, when high level I/ O operations (e.g. © 
open( ), write({)) are pertomned on the device, the calls will be routed 
through rawFsLib. 


This routine associates volName with a device and installs it in the Vx960 I/O 
System's device table. The driver number used when the device is added to 
the table is that which was assigned to the raw library during rawFsInit{ ). 
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(The driver number is kept in the global variable rawFsDruNum.) 


The BLK_DEV structure specified by pBlkDev contains configuration data 
describing the device and the addresses of five routines which will be called 
to read blocks, write blocks, reset the device, check device status, and per- 
form other control functions (ioctl( )). These routines will not be called until 
they are required by subsequent I/O operations. 


RETURNS 
A pointer to the volume descriptor (RAW_VOL_DESC), or NULL if there is 


an error. 


SEE ALSO 
rawFsLib 


NAME 


rawFsInit{ ) - prepare to use the raw volume library . 


SYNOPSIS 
STATUS rawFsiInit Nese liaes 
int wmaxFiles; /* max # of simultaneously open files :*/— 


DESCRIPTION — 
This routine initializes the raw: volume’: ‘library. It must. be called. exactly 
once, before any other routine:incthe:library:y Thé-argumient specifies’ the:: 
number of file: descriptors that: maybe open-at-once:*:This: rdutine allocates 


and sets up the necessary tama seeds 


This routine also installs raw volime:litraryiroutinesin:the Vx960:5/. Ousyg* is 
tem driver table. The driver ntmmberassignett.to! rawFsLib isiplacediini the? 


global variable rawFsDruNum. Fhissiumbeb wilt asanitilchslarsebanican ae 
tem file descriptors opened to rawFs:devicesiisicrs coenest tere 


To enable this initialization, idefine cINGLUDE:: RAWES: sin: ponfigADL 
rawFsInit( ) will then. be called’: from’ the! roots task, «usrRoot(),: in” 
usrConfig.c. 


RETURNS 
OK, or ERROR. 


SEE ALSO 
rawFsLib 
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NAME 
rawFsModeChange( ) - modify mode of raw device volume 


SYNOPSIS 
VOID raw’ sModeChange (vdptr, newhode) | 
RAW VOL DESC ‘tvdptr; /* pointer to volume descriptor */ 
int pevtode; /* READ/WRITE/UPDATE (both) */ 


DESCRIPTION 
This routine sets the device’s mode to newMode by setting the mode field in 
the BLK_DEV structure. This routine should be called whenever the read 
and write capabilities are determined, usually after a ready change. See the 
manual entry for rawFsReadyChange( ). 


The driver's device initialization routine should initially set the mode to 
UPDATE (i.e., both READ and WRITE). 


RETURNS 
N/A 


SEE ALSO 
rawFsLib 


NAME | 
rawFsReadyChange(.) - notify rawFsLib of a change in ready status, 


SYNOPSIS 2 
VOID rav’sReadyChange (vdptr) : 
RAW _VOL_DESC ‘*vdptr; /* pointer to volume descriptor */ 


DESCRIPTION ; 
This routine sets the volume descriptor state — to 
RAW_VD_READY_CHANGED. It should be called whenever a driver 
senses that a device has come on-line or gone off-line, (e.g., a disk has been 
inserted or removed). 


After this routine has been called, the next atternpt to use the volume will 
result in an attempted remount. 


1 - 260 Intel | Rev:29 Aug 91 


Libraries (1) rawWFSLib 


RETURNS 
N/A 


SEE ALSO 
rawFsLib 
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NAME 
rawFsVolUnmount{ ) - disable a raw device volume 


SYNOPSIS 
STATUS ravi’sVolUnmount (vdptr) 
RAW VOL DESC ‘*vdptr; /* pointer to volume descriptor */ 


DESCRIPTION 
This routine is called when I/O operations on a volume are to be discontin- 
ued. This is commonly done before changing removable disks. All buffered 
data for the volume is written to the device (if possible), any open file 
descriptors are marked as obsolete, and the volume is marked as not 
mounted. 


Because this routine will flush data from memory to the physical device, it 
should not be used in situations where the disk-change is not recognized 
until after a new disk has been inserted. In these circumstances, use the 
ready-change mechanism (see the manual entry for rawFsReadyChange( )). 


This routine may also be called by issuing an ioctl() call using the © 
FIOUNMOUNT function code. SO ; , 


RETURNS | ee oat, 
OK, or ERROR if the routine cannot access the volume. 


SEE ALSO 
rawFsLib 


é 
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NAME 
rebootLib - reboot support library 


SYNOPSIS 
reboot{( ) - reset network devices and transfer control to boot ROMs 
rebootHookAdd( ) - add a routine to be called at reboot 


VOID reboot (startType) 
STATUS rebootHookAdd (rebootHook) 


DESCRIPTION 

This library provides reboot support. To restart Vx960, the routine reboot{ ) 
can be called at any time by typing “X from the shell. Shutdown routines 
can be added with rebootHookAdd(). These are typically used to reset or 
synchronize hardware. For example, netLib adds a reboot hook to cause all 
network interfaces to be reset. Once the reboot hooks have been run, 
sysToMonitor( ) is called to transfer control to the boot ROMs. See the 
manual entry for bootInit. 


DEFICIENCIES 
The order in which. hooks are added is the order in which they are run. Asa 
result, netLib will kill the network, and no user-added hook routines will be 
able to use the network. There is no rebootHookDelete( ). 


INCLUDE FILE 
sysLib.h 


SEE ALSO : : 
sysLib, bootConfig, bootInit — 


NAME 
reboot{ ) - reset network ‘devices arid transfer control to boot ROMs 


SYNOPSIS | , 
VOID reboot (startType) | 
int startType; /* how the boot ROMS will reboot */ 
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DESCRIPTION 
This routine returns control to the boot ROMs after calling a series of prel- 
iminary shutdown routines that have been added via rebootHookAdd( ), 
including routines to reset all network devices. 


The bit values for startType are defined in sysLib.h: 


BOOT_NORMAL - causes the system to go through the countdown 
sequence and try to reboot Vx960 automatically. 
Memory is not cleared. 


BOOT_NO_AUTOBOOT 
- causes the system to display the Vx960 boot 
prompt and wait for user input to the boot ROM 
monitor. Memory is not cleared. 


BOOT_CLEAR - the same as BOOT_NORMAL, except that 
memory is cleared. 


BOOT_QUICK_AUTOBOOT | 
| - the same as BOOT_NORMAL, except the count- 
down is shorter. 


RETURNS 
N/A 


SEE ALSO 
rebootLib, sysToMonitor{ ), rebootHookAdd( ) 


NAME 


rebootHookAdd{ ) - add a routine to be called at reboot 


SYNOPSIS 
STATUS rebootHookAdd (rebootHook) 
FUNCPTR rebootHook; /* routine to be called at reboot */ 


DESCRIPTION | 
This routine adds the specified routine to a list of routines to be called when 
Vx960 is rebooted. The specified routine should be declared as follows: 


VOID rebootHcok (startType) 
int startType; /* startType is passed to all hooks * 
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RETURNS 
OK, or ERROR if memory is insufficient. 


SEE ALSO 
rebootLib, reboot{ ) 
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NAME 
remLib - remote command library 


SYNOPSIS 
rcmd( ) - execute a shell command on a remote machine 
rresuport( ) - open a socket with a privileged port bound to it 
remCurIdGet( ) - get the current user name and password 
remCurIdSet( ) - set the remote user name and password 
1am() - set the remote user name and password 
whoami( ) - display the current remote identity 
bindresvport( ) - bind a socket to a privileged IP port 


int romd (host, remotePort, localUser, remoteUser, and, fd2p) 
int rresvport (alport) 

VOID remCurIdGet (user, passwd) 

STATUS remCurIdSst (newJser, newPasswd) 

STATUS iam (newUser, newPasswi) eae 

VOID whoami () 

STATUS bindresvport (sd, sin) 


DESCRIPTION 
This library supplies routines found: under-BSD 4.2 (rcmd and rresvport), 
and the routines that provide authorization for network file access via 
netDrv and remote command execution via rcmd. 


INCLUDE FILE 
remLib.h 
SEE ALSO UR ees 
inetLib, Programmer's Guide: Networkn-*' 5, Cregessarcc fo ak 


> 
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NAME 3 
rcmd() - execute a shell command onaremote-machine 


SYNOPSIS | 
int remd (host, remotePort, localUser, remoteUser, cond, fd2p) 
char *host; /* host name or inet address */ 
int remotePort; /* remote port to connect to (rshd) */ 
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char ‘*localuser; /* local user name */ 
char ‘*remoteUser; /* resote user name */ 
char ‘*cnd; /* command */ 
int *fd2p; /* if this pointer is non-zero, stderr socket 
« is opened and socket descriptor is filled in */ 
DESCRIPTION 


This routine executes a command on a remote machine, using the remote 
shell daemon (rshd) on the remote system. It is analogous to the UNIX com- 
mand remd. 


RETURNS 
A socket descriptor if the remote shell daemon accepts, or ERROR if the 


remote command fails. 


SEE ALSO 
remLib, BSD 4.2 manual entry for remd 


NAME 


rresvport( ) - open a socket with a privileged port bound to it 
SYNOPSIS 
int rresvport (alport) 
int ‘*alport; /* port number to initially try */ 
DESCRIPTION 


This routine opens a socket with a privileged Eon bound to it. It i is analo- 
gous to the UNIX command rresuport. . 


RETURNS 
A socket descriptor or ERROR if either the socket cannot be opened or all 
ports are in use. 


SEE ALSO 
remLib, BSD 4.2 aunaal — for rresuport | ot 
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NAME 


remCurldGet( ) - get the current user name and password 


SYNOPSIS 
VOID resCurIdGet (user, passwd) 
char ‘user; /* where to return current user name */ 
char ‘passwd; /* where to return current password */ 


DESCRIPTION 
This routine gets the user name and password currently being used for 
remote host access privileges and copies them to user and passwd. Either 
parameter can be initialized to NULL, and the corresponding item will not 
be passed. | 


RETURNS 
N/A 


SEE ALSO 
remLib, iam(), whoami() 


NAME 


remCurldSet( ) - set the remote user name and password 


SYNOPSIS 
STATUS remCurlIdset (naidiaex, newPasswd ) . A 
char *newUser; /* user name to use on remote */ on 
char ‘*newPasowd; /* password to use on remote (MULL = none) */ 


DESCRIPTION 
This routine specifies the user name that will have access privileges:on -the..’ 
remote machine. The user name must exist in the remote machine's: 


/etc/passwd, and if it has been assigned a password, the password must: be «:::-:, 


specified in newPasswd. 
Either parameter can be NULL, and the corresponding item will not be set. - - 


The maximum length of the user name and the password is 
MAX_IDENTITY_LEN (defined in remLib.h). 
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RETURNS 
OK, or ERROR if the name or password is too long. 


SEE ALSO 
remLib, iam(), whoami( ) 
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NAME 


iam() - set the remote user name and password 


SYNOPSIS 
STATUS iam (newUser, newPasswi) 
char ‘*newJser; /* user name to use on remote */ 
char *newPasswd; /* password to use on remote (MULL = none) */ 


DESCRIPTION 
This routine specifies the user name that will have access privileges on the 
remote machine. The user name must exist in the remote machine's 
/etc/passwd, and if it has been assigned a password, the password must be 
specified in newPasswd. 


Either parameter can be NULL, and the corresponding item will not be set. 


The maximum length of the user mame and the password is 
MAX_IDENTITY_LEN (defined in remLib.h). 


RETURNS | 
OK, or ERROR if'the call fails. . 


SEE ALSO eis 4% 
remLib, whoami#(-), femCurldGet{ ),:remCurldSet() 


NAME 


whoami( ) - display the current remote identity 


SYNOPSIS 
VOID whoami () 


1 - 268 Intel Rev: 29 Aug 91 


Libraries (1) remLib 


DESCRIPTION 
This routine displays the user name currently used for remote machine 


access. The user name is set with tam() or remCurIdSet{ ). 


RETURNS 
N/A 


SEE ALSO 
rem Lib, iam({ ), remCurIdGet{ ), remCurIdSet( ) 


NAME 
bindresvport( ) - bind a socket to a privileged IP port 


SYNOPSIS 
STATUS bindresvport (sd, sin) 
int sd; /* socket to be bound */ 
struct sockaddr_in ‘sin; /* socket address -- value/result */ 


DESCRIPTION 
Privileged IP ports (numbers between and including 0 and 1023) are 
reserved for privileged programs. The bindresvport() routine will pick a— 
port number between 600 and 1023 that is not being used by any other. pro- 
grams and bind the socket passed as sd to that port. 


RETURNS 
OK, or ERROR if the address family specified in sin is not supported or the 


call fails. 


SEE ALSO 
remLib 
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NAME 
rlogLib - remote login library 


SYNOPSIS 
rlogInit( ) - initialize the remote login facility 
rlogind( ) - the Vx960 remote login daemon 
rlogin( ) - log in to a remote host 


STATUS rlogInit () 
VOID rlogind () 
STATUS rlogin (host) 


DESCRIPTION 
This library provides a remote login facility for Vx960 that uses the UNIX 
rlogin protocol as implemented in UNIX BSD 4.2 to allow users at a Vx960 
terminal to. login to remote systems via the network; and allow users at 
remote systems to log in to Vx960 via the network. 


A Vx960 user may log in to any other remote Vx960 or UNIX system via the 
network, by calling rlogin() from the shell. 


The remote login daemon, rlogind( ), allows remote users to log into Vx960. 
The daemon is started by calling rlogInit(); if- INCLUDE_RLOGIN is 
defined in configAll.h, it is called by the root task, usrRoot(), in 
usrConfig.c. The remote login daemon accepts remote login requests from 
another Vx960 or UNIX system, and causes. the shell’s input and output, to 
be redirected to the remote user. 


Internally, rlogind() provides a tty-like interface to the remote | user sea al 
the use of the Vx960 enero driver piyDevi - os 


SEE ALSO re 
ptyDrv, telnetLib; “UNIX-documentation for rlogin, rlogind; and. pty - :- 


Jf 


SAbenieancanennnnend 


NAME 
rlogInit{( ) - initialize the remote login facility 
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SYNOPSIS 
STATUS rlogInit () 


DESCRIPTION 
This routine initializes the remote login facility. It creates a pty device, and 
spawns rlogind(). If INCLUDE_RLOGIN is defined in configAILh, it is 
called from usrRoot( ) in usrConfig.c, before any other system tries to 08} in 
to this Vx960 system via the UNIX rlogin protocol. 


RETURNS 
OK, or ERROR. 


SEE ALSO 
rlogLib 


NAME 


rlogind( ) - the Vx960 remote login daemon 


SYNOPSIS 
VOID rlogind () 


DESCRIPTION 
This routine provides a facility for remote users to log into Vx960 over the 
network. If INCLUDE_RLOGIN is: defined:in configAlLh, it is spawned by 
rlogInit( ), which is called by the root‘ task} us#Roott ),in-usrConfig.c. .... 


‘Remote login requests will cause stdinzstdoutand:stderr.to be: directed:away - : 
from the console. When the remote usér:disconhects;!stdin;. stdout,and.stderr - - 


are restored, and the shell is restarted. -rlogind(jiudes theitemoteéarservetifi7: :-? 


3 ne 


— 


cation protocol specified by the UNDinemotechelledaenidn ddcuniieiitation;: shh 


but ignores all the information exceptthe-user: namé;Wwhich:i is. used to’sét the : 


Vx960 remote identity (see the maial'entry-for zam(')).‘: 


The remote login. daemon requires: the:existence-of! a:pseudo-tetminal. dev-.. 
ice, which is created by rlogInit( }. before: rlogind(3-As: spaiwned.: ‘tlogind( ) 


creates two child processes, rlogInTask-and.rldg@i:t Task; -whenéver. a-remote 


user is logged in. These prereee exit when‘the remote connection is ter- ~ 


minated. 


RETURNS 
N/A 
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SEE ALSO 
rlogLib, tam() 
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NAME 
rlogin( ) - log in to a remote host 


SYNOPSIS 
STATUS rlogin (host) 
cher ‘*host; /* name of host to connect to */ 


DESCRIPTION | 
This routine allows users to log in to a remote host. It may be called from 
the Vx960 shell as follows: 


-> rlogin “remoteSysten" 


where remoteSystem is either a host name which has been previously added 
to the remote host table by a call to hostAdd( ), or an Internet address in dot 
notation (e.g., ““90.0.0.2"). The remote system will be logged into with the 
current user name as set by a call to iam(). 


The user disconnects from the remote system by typing: 


ow 
e 


as the only characters on the line, or by simply logging out from the remote 
system using logout{ ). 


OK, or ERROR if he ee aan eee no privileged -ports are available, the 
routine is unable to connect to the host, or the child process cannot be 
spawned. | i 


SEE ALSO 
rlogLib, iam( ), logout{ ) 
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NAME 


rmgLib - ring buffer subroutine library 


SYNOPSIS 
rngCreate( ) - create an empty ring buffer 
rngDelete( ) - delete a ring buffer 
_rngFlush( ) - make a ring buffer empty 
rngBufGet( ) - get characters from a ring buffer 
rngBufPut( ) - put bytes into a ring buffer 
rngisEmpty( ) - test if a ring buffer is empty 
rngIsFull( ) - test if a ring buffer is full (no more room) 
rngFreeBytes( ) - determine the number of free bytes in a ring buffer 
rngNBytes( ) - determine the number of bytes in a ring buffer 
rngPutAhead{ ) - put a byte ahead ina ring buffer without moving ring pointers 
rngMoveAhead( ) - advance a ring pointer by n bytes 


RING ID rngCreate (nbytes) 

VOID rngDelete (ringId) 

VOID rngFflush (ringId) 

int rngBufGet (rngId, buffer, maxbytes) 
int rngBufPut (xrngId, buffer, eraeeer 
BOOL rngIsEmpty (ringId) 

BOOL rngIsFull (ringId) 

int rng¥freeBytes (ringId) 

int rngMBytes (ringId) 

VOID rngPutAhead (ringId, byte, eerere 
VOID rngMovedhead (ringId, n) 


DESCRIPTION 
This library provides routines for creating and using ring buffers, which:are:::-1 317: 
first-in-first-out circular buffers. The routines simply manipulate the sing. mere 


buffer data structure; no kernel functions are invoked. In particular, : wing Prats 
buffers by themselves provide no task synchronization or mutual exclusion, ‘:.--+:) +4 


However, the ring buffer pointers are manipulated in such a way that ao 
reader task (invoking mgBufGet( )) and a writer task (invoking 
rngBugPut()) can access a ring simultaneously without requiring mutual » 
exclusion. This is because readers only affect a read pointer and writers only 

affect a write pointer in a ring buffer data structure. However, access by 
multiple readers or writers must be interlocked through a mutual exclusion 
mechanism (i.e., a mutual-exclusion semephore guarding a ring buffer). 
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This library also supplies two macros, RNG _ELEM_PUT and 
RNG_ELEM GET, for putting and getting single bytes from a ring buffer. 
They are defined in rngLib.h. 


int RNWG_ELEM GET (ringId, pch, fromP) 
int RNG ELEM PUT (ringId, ch, toP) 


Both macros require a temporary variable fromP or toP, which should be 
declared as “register int” for maximum efficiency. RNG ELEM_GET 
returns 1 if there was a character available in the buffer; it returns 0 other- 
wise. RNG ELEM _PUT returns 1 if there was room in the buffer; it returns 0 
otherwise. These are somewhat faster than rngBufPut{ ) and rngBufGet( ), 
which can put and get multi-byte buffers. 


INCLUDE FILE 
rngLib.h 


NAME 
rngCreate( ) - create an empty ring buffer 


SYNOPSIS 
RING ID rngCreate (nbytes) 
int nbytes; /* number of bytes in ring buffer */ 


DESCRIPTION 
This routine creates a ring buffer of size nbytes, and initializes it. Memory for 
the buffer is allocated from:the system memory partition. 


RETURNS a 
ID of ie ring buffer, or NULLif memory.cannot be allocated. 


SEE ALSO 
rng Lib 
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NAME 
rngDelete( ) - delete a ring buffer 
SYNOPSIS 


VOID rngDelete (ringId) 
RING ID ringId; /* ring buffer to delete */ 


DESCRIPTION 
This routine deletes a specified ring buffer. Any data currently i in the buffer 
will be lost. 


RETURNS 
N/A 


SEE ALSO 
rngLib 
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NAME 
rngFlush() - make a ring buffer empty 


SYNOPSIS 
VOID rng¥flush (ringId) 
RING ID ringid; /* ring buffer to initialize */ 


DESCRIPTION 
This routine initializes a specified TANG buffer to be gs Any data 
currently in the buffer will be lost. 


RETURNS 
N/A 


SEE ALSO 
rmgLib 
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NAME 
rngBufGet{ ) - get characters from a ring buffer 
SYNOPSIS 2 
int rngBufGet (rngId, buffer, maxbytes) 
RING ID rngId; /* ring buffer to get data from «/ 
char *buffer; /* pointer to buffer to receive data */ 
int maxbytes; /* maximum number of bytes to get +f 
DESCRIPTION 


This routine copies bytes from the ring buffer rngld into buffer. It copies as 
many bytes as are available in the ring, up to maxbytes. The bytes copied will 
be removed from the ring. | 


RETURNS | : 
The number of bytes actually received from the ring buffer; it may be zero if 
the ring buffer is empty at the time of the call. 


SEE ALSO 
mgLib 


NAME 


rngBufPut( ) - put bytes into a ring buffer 


SYNOPSIS , 


int rogeufPut (rngid, buffer, ‘nbytes): freyiid, Se Phe A 
RING_ID rngId; /* ring: buffer to put data into */ 


char tbuffer; /* buffer to get data: from ef 
int nbytes; /* number of bytes to try to put. */ 


DESCRIPTION ; 
| This routine puts bytes from buffer into ring buffer ringld. The specified 
number of bytes will be put into the ring, up to the number of bytes avail- 
able in the ring. 


RETURNS 
The number of bytes actually put into the ring buffer; it may be less than 
number requested, even zero, if there is insufficient room in the ring buffer 
at the time of the call. 
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NAME 


rngisEmpty( ) - test if a ring buffer is empty 


SYNOPSIS 
BOOL rngIisEmpty (ringId) 
RING ID ringId; /* ring buffer to test */ 


DESCRIPTION 

This routine determines if a specified ring buffer is empty. 
RETURNS 

TRUE if empty, FALSE if not. 


SEE ALSO 
mgLib 


NAME 

rngIsFull( ) - test if a ring buffer is full (no more room) 
SYNOPSIS PTR 

BOOL rngIsFull (ringId) - SUIS aR geet ge 

RING_ ID ringId; /* xing buffer'to test */ 

DESCRIPTION 

This routine determines if a specified ring buffer is completely full. 
RETURNS ; 

TRUE if full, FALSE if not. 
SEE ALSO 

mgLib 
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NAME 
rngFreeBytes() - determine the number of free bytes in a ring buffer 


SYNOPSIS 


int rngFreeBytes (ringId) 
RING ID ringId; /* ring buffer to examine */ 


DESCRIPTION | 
This routine determines the number of bytes currently unused in a specified 
ring buffer. 


RETURNS 
The number of unused bytes in the ring buffer. 


SEE ALSO 
mgLib 


NAME 
rngNBytes() - determine the number of bytes in a ring buffer 


SYNOPSIS 
int rngsBytes (ringlId) 
RIRG_ ID ringId; /* ring buffer to be eaumerated */ 


DESCRIPTION 
This routine determines the number of bytes currently in a specified ring 
buffer. a 


RETURNS aS 
The number of bytes filled in the ring buffer. a 


SEE ALSO 
mgLib 


1-278 Intel Rev: 29 Aug 91 


Libraries (1) mngLib > 


Rae BSAA ORES : 
oratate ~ SS 


anes 


NAME 
rngPutAhead() - put a byte ahead in a ring buffer without moving ring 
pointers : 


SYNOPSIS 
VOID rngPutAhead (ringId, byte, offset) 
RING ID ringId; /* ring buffer to put byte in «/ 


char byte; /* byte to be put in ring «/ 
int offset; /* offset beyond next input byte */ 
/* where to put byte «/ 
DESCRIPTION 


This routine writes a byte into the ring, but does not move the ring buffer 
pointers. Thus the byte will not yet be available to rngBufGet() calls. The 
byte is written offset bytes ahead of the next input location in the ring. Thus, 
an offset of 0 puts the byte in the same position as would RNG_ELEM_ PUT 
would put a byte, except that the input pointer is not updated. 


Bytes written ahead in the ring buffer with this routine can be made avail- 
able all at once by subsequently moving the ring buffer pointers with the 
routine rngMoveAhead{ ). 


Before calling rngPutAhead( ), the-caller must verify that at least offset + 1 
bytes are available in the ring buffer. : 


RETURNS 
N/A 


SEE ALSO 
mgLib 


NAME . 
rngMoveAhead( ) - advance a ring pointer by.n bytes 
SYNOPSIS 
VOID rngMoveAhead (ringId, n) 
RING ID ringId; /* ring buffer to be advanced «/ 
int | Bn} /* number of bytes ahead to move input pointer */ 
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DESCRIPTION 
This routine advances the ring buffer input pointer by n bytes. This makes n 
bytes available in the ring buffer, after having been written ahead in the ring 
buffer with rngPutAhead( ). | 


RETURNS 
— N/A 


SEE ALSO 
rmgLib 
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routeLib - network route manipulation library 


SYNOPSIS 
routeAdd{ ) - add a route 
routeDelete( ) - delete a route 
routeShow( ) - display host and network routing tables 


STATUS routeAdd (destination, gateway) 
STATUS routeDelete (destination, gateway) 
VOID routeShow () 


DESCRIPTION 
This library contains the routines routeAdd() and routeDelete( ) for chang- 
ing and examining the network routing tables. Routines are provided for 
adding and deleting routes that go through a passive gateway. The routine 
routeShow() displays the routing tables. Vx960 has no routing daemon; 
therefore, the tables must be maintained manually. 


SEE ALSO 
hostLib, Programmer's Guide: Network 
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NAME 
routeAdd{ ) - adda route 
SYNOPSIS 
STATUS routeAdd (destination, gateway) 
char ‘*destination; /* inet address or name of route destination «/ 
char “gateway; /* inet address or name of gateway to destination */: 
DESCRIPTION 


This routine adds gateways to the network routing tables. It is called from a 
Vx960 machine that needs to establish a gateway to a destination network 
(or machine). 


Both destination and gateway can be specified in standard Internet address 
format (e.g., 90.0.0.2) or by their host names, as specified by hostAdd{ ). 
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EXAMPLE 
The call: 


tells Vx960 that the machine with the host name “‘gate” is the gateway to 
network 90.0.0.0. The host “gate” must already have been created by hos- 
tAdd. | 


The call: 
routeAdd ("90.0.0.0", 91.0.0.3") 


tells Vx960 that the machine with the Internet address 91.0.0.3 is the gateway 
to network 90.0.0.0. 


The call: 
routeAdd (“destination", “gate”) 
tells Vx960 that the machine with the host name “gate” is the gateway to the 


machine named “‘destination’’. The host names “‘gate’’ and “destination” 
must have already been created by hostAdd{ ). 


The call: 

routeAdd ("0", “gate") 
tells Vx960 that the machine with the host name “gate’ is the default gate- 
way. The host “gate” must already have been created by hostAdd(). A 


default gateway is where IP datagrams are routed when there is no specific 
routing table entry available for the destination IP network or host. 


RETURNS 
OK or ERROR. 


SEE ALSO a oe 
routeLib, Programmer's Guide: Network 


NAME 
routeDelete( ) - delete a route © 
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SYNOPSIS 
STATUS routeDelete (destination, gateway) 
char ‘destination; /* inet address or name of route destination «f 
char ‘*gateway; /* inet address or name of gateway to destination */ 
DESCRIPTION 
This routine deletes a specified route from the network routing tables. 
RETURNS 
OK or ERROR. 
SEE ALSO 


routeLib, routeAdd( ), Programmer's Guide: Network 


NAME 

routeShow({ ) - display host and network routing tables 
SYNOPSIS 

VOID routeShow () 
DESCRIPTION 


This routine displays the current routing information in the routing table. 
EXAMPLE © 


=> routesShow 

ROUTE MET TAELZE 

destination gateway flags Refcnt Use Interface 
90.0.0.0 90.0.0.63 i 1 142 enpd 


ROUTE HOST TAELE 
destination gateway flags Refcnt Use Interface 


127 .0.0.1 127.0.0.1 5 0 82 100 


_ The flags field represents a decimal value of the flags specified for a given 
route. The following is a list of currently available flag values: 


Ox] - route is usable (i.e., “up’) 
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0x2 - destination is a gateway 

Ox4 - host specific routing entry 

0x10 - created dynamically (by redirect) 
0x20 © - modified dynamically (by redirect) 


In the above example, the entry in the ROUTE NET TABLE has a flag value 

of 1, which indicates that this route is ““up”’ and usable and network specific 

(the Ox4 bit is turned off). The entry in the ROUTE HOST TABLE has a flag 

value of 5 (0x1 OR’ed with 0x4), which indicates that this route is “up’’ and 
_ usable and host specific. | 


RETURNS 
N/A 


SEE ALSO 
routeLib, Programmer's Guide: Network 
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NAME 


rpcLib - RPC support library 


SYNOPSIS 


rpcInit( ) - initialize RPC package 


_rpcTaskInit{ ) - initialize a task’s access to the RPC package 


STATUS rpcInit () 
STATUS rpcTaeskInit () 


DESCRIPTION 


This library supports Sun Microsystems’ Remote Procedure Call (RPC) facil- 
ity. RPC provides facilities for implementing distributed client /server- 
based architectures. The underlying communication mechanism can be 
completely hidden, permitting applications to be written without any refer- 
ence to network sockets. The package is structured such that lower-level 
routines can optionally be accessed, allowing greater control of the com- 
munication protocols. 


For more information and a tutorial on RPC, see Sun’s Remote Procedure Call 
Programming Guide. 

The RPC facility is enabled by defining INCLUDE_RPC in configAILh or in 
the config.h file for the target CPU. ai 


Vx960 supports, Network File System (NFS) and gdb960, which are built on 
top of RPC. If NFS or INCLUDE: RDB:(remote debug) is eee into the 
Vx960 system, RPC is raed ‘included.as well: _ 


IMPLEMENTATION 


A task must call rpcTaskInit( ) before. maine: any calls :to-other: routines in . 


the RPC library. This routine creates ata lacked ‘data-structures required - - 


by RPC. ; 


Because each task has its own-RPG. context,: RPC-related objects (such as 
SVCXPRTs and CLIENTs) cannot:be ‘shated.among -tasks; objects created by 
one task cannot be passed to another for use. : The task-specific data struc- 
tures are automatically deleted when the task exits. 


INCLUDE FILE 


rpc.h 


SEE ALSO 


nfsLib, nfsDrv, dbxLib, Sun’s RPC Programming Guide 
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NAME 
rpcInit( ) - initialize RPC package 


SYNOPSIS 
STATUS rpcInit () 


DESCRIPTION 
This routine must be called before any task can use RPC; it spawns the port- 
map daemon. If INCLUDE_RPC is defined in configAII.h, it is called by the 
root task usrRooft( ) in usrConfig.c. 


RETURNS 
OK, or ERROR if the portmap daemon cannot be spawned. 


SEE ALSO 
rpcLib 


NAME 
rpcTaskInit{ ) - initialize a task’s access to the RPC package 


SYNOPSIS 
STATUS rpcTaskInit () 


DESCRIPTION 
| This routine must be called by a task before it makes any calls to other rou- 


tines in the RPC package. 


RETURNS 
OK, or ERROR if there is insufficient memory or the routine is unable to add 


a task delete hook. 


SEE ALSO | 
rpcLib 
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NAME 
rt11FsLib - RT-11 media-compatible file system library 


SYNOPSIS | 
rt11FsDevInit{ ) - initialize the RT-11 device descriptor 
rt11FsInit( ) - prepare to use the RT-11 library 
rt11FsMkfs( ) - initialize a device and create an RT-11 Sa system 
rt11FsDateSet{( ) - set the current date 
rt11FsReadyChange( ) - notify rtl11FsLib of a change in vay status 
rt11FsModeChange( ) - modify the mode of an RT-11 volume 


RT VOL_DESC ‘rtllFsDevinit (devlame, pBlkDev, rtllFet, nEatries, changeNoWarn) 
STATUS rtliFsInit (maxFiles) | 

RT VOL DESC *rtllFsHkfs (voliHame, pBlkDev) 

YOID rtllFsbdateSet (year, month, day) 

VOID rtllFsReadyChange (vdptr) 

VOID rtllFsModeChange (vdptr, naetéode) 


DESCRIPTION 
This library provides services for file-oriented device drivers which use the 
RT-11 file standard. This module takes care of all the buffering, directory 
maintenance, and RT-11-specific details necessary. 


USING THIS LIBRARY 
The various functions provided by the Vx960 rt11Fs file system may be 
separated into three broad groups: ene: initialization, device initializa: ‘- 
tion, and file system operation. | 


The rt11FsInit( ) function is the principal ee function; it need only | 
be called once, regardless of how many rt11Fs devices will be used. 


Other rt11Fs functions are used for device initialization. For each rtl1Fs_ . 
device, either. rt11FsDevInit( ) or rt11FsMkfs( ) must be called to install the < } 
device and define its configuration. 


Lastly, several functions are provided to inform the file system of changes in «.: 
the system environment. The rt11FsDateSet() function is used to set the - 
current date. The rt11FsModeChange( ) call may be used to modify the rea- 
dability or writability of a particular device. Finally, the 
rt11FsReadyChange( ) function is used to inform the file system that a disk 
may have been swapped, and that the next disk operation should first 
remount the disk. 


More detailed information on all of these functions is discussed in the 
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following sections. 


INITIALIZING RTIIUB 
Before any other routines in rt1iFsLib can be used, the routine rt11Fsinii{ ) 
must be called to initialize this library. This call specifies the maximum 
number of RT-11 files that can be open simultaneously and allocates 
memory for that many RT-11 file descriptors. Attempts to open more RT-11 
files than the specified maximum will result in errors from open( ) or creat( ). 


To enable this initialization, define INCLUDE_RTIIFS in ere 
rt11FsInit{) will then be called from the root task, usrRoot(), i 
usrConfig.c. 


DEFINING AN RT-11 DEVICE 

To use this library for a particular device, the device structure must contain, 
as the very first item, a BLK_DEV structure. This must be initialized before 
calling rt11FsDevInit{). In the BLK _DEV structure, the driver includes the 
addresses of five routines which it must supply: one that reads one or more 
sectors, one that writes one or more sectors, one that performs I/O control 
on the device (using ioctl()), one that checks the status of the device, and 
one that resets the device. This structure also specifies various physical 
aspects of the device (e.g., number of sectors, sectors per track, whether the 
media is removabie). See Programmer's Guide: I/O System for more informa- 
tion on defining block devices. 


The device is associated with the RT-11 file system via the rt11FsDevInii( ) 
call. The arguments to rt11FsDevInit{ ) include the name to be used for the 
RT-11 volume, a pointer to the BLK_DEV structure, whether the device uses 
RT-11 standard skew and interleave, and the maximum number of files that 
can be contained in the device directory. 


Thereafter, when the file system receives a request from the I/O system, it 
simply calls the provided routines in the device driver to fulfill the request. 


RTFRAT ute 

_ .The RT-11 standard defines a peculiar software interleave and track-to-track 
skew as part of the format. The rtFmé parameter passed to rt11FsDevInit( ) 
should be TRUE if this formatting is desired. This should be the case if strict 
RT-11 compatibility is desired, or. if files. must be transferred between the 
development and target machines ‘using the Vx960-supplied RT-11 tools. 
Software interleave and skew will automatically be dealt with by rt11FsLib. 


When rtFmt has been passed as TRUE and the maximum number of files is 
specified RT_FILES FOR_2_ BLOCK _SEG, the driver does not need to do 
anything else (except to add the track offset as described above) to maintain 
RT-11 compatibility. 


Note that if the number of files specified is different than 
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| RT_FILES FOR_2_ BLOCK_SEG under either a Vx960 system or an RT-11 
system, compatibility is lost because Vx960 allocates a contiguous directory, 
whereas RT-11 systems create chained directories. 


MULTIPLE LOGICAL DEVICES AND RT-11 COMPATIBILITY 

The sector number passed to the sector read and write routines is an abso- 
lute number, starting from sector 0 at the beginning of the device. If desired, 
the driver may add an offset from the beginning of the physical device 
before the start of the logical device. This would normally be done by keep- 
ing an offset parameter in the device-specific structure of the driver, and 
adding the proper number of sectors to the sector number passed to the read 
and write routines. 


The RT-11 standard defines the disk to start on track 1. Track 0 is set aside 
for boot information. Therefore, in order to retain true compatibility with 
RT-11 systems, a one-track offset (i-e., the number of sectors in one track) 
needs to be added to the sector numbers passed to the sector read and write 
routines, and the device size needs to be declared as one track smaller than it 
actually is. This must be done by the driver using rt11FsLib; the library does 
not add such an offset for you. 


In the Vx960 RT-11 implementation, the directory is a fixed size, able to con- 
tain at least as many files as specified in the call to r#11FsDevInit( ). If the 
maximum number of files is specified to be RT_FILES FOR_2 BLOCK _SEG, 
strict RT-11 compatibility is maintained, because this is the initial allocation 
in the RT-11 standard. 


RT-11 FILE NAMES , 
File names in the RT-11 file system use a six-character filename, followed by 
a period (.), followed by an optional three-character extension. 


DIRECTORY ENTRIES 

An ioctl( ) call with the FIODIRENTRY function returns information about a 
particular directory entry. A pointer to a REQ _DIR_ENTRY structure is 
passed as the parameter. The field entryNum in the REQ_DIR_ENTRY struc- 
ture must be set to the desired entry number. The name of the file, its size 
(in bytes), and its creation date are returned in the structure. If the specified 
entry is empty (ie., if it represents an unallocated-section of the disk), the 
name will be an empty string, the size will be the size of the available disk 
section, and the date will be meaningless. Typically, the entries are accessed 
sequentially, starting with entryNum = 0, until the terminating entry is 
reached, indicated by a return code of ERROR. 


DIRECTORIES IN MEMORY 
A copy of the directory for each volume is kept in memory (in the 
RT_VOL_DESC structure). This speeds up directory accesses, but requires 
that rtlLFsLib be notified when disks are changed (i.e, floppies are 
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swapped). If the driver can find this out (by interrogating controller status 
or by receiving an interrupt) the driver simply calls rt11FsReadyChange( ) 
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try to remount the device next time it needs it. 


If the driver does not have access to the information that disk volumes have 
been changed, the changeNoWarn parameter should be set to TRUE when the 
device is defined using rt11FsDevInit(). This will cause the disk to be 
automatically remounted oor each open(), creat(), delete(), and direc- 
tory listing. 


The routine rt11FsReadyChange( ) can also be called by user tasks by issu- 
ing an ioctl( ) call with FTODISKCHANGE as the function code. 


ACCESSING THE RAW DISK 

As a special case in open() and creat{ ) calls, rt11FsLib recognizes a null file 
name to indicate access to the entire “‘raw’ disk, as opposed to a file on the 
disk. Access in raw mode is useful for a disk that has no file system. For 
example, to initialize a new file system on the disk, use an ioctl() call with 
FIODISKINIT. To read the directory of a disk for which no file names are 
known, open the raw disk and use an ioctl() call with the function 
FIODIRENTRY. 


RT-11 HINTS 
The RT-11 file system is much simpler than the more common UNIX or MS- 
DOS file systems. The advantage of RT-11 is its speed; file access is made in 
at most one seek because all files are contiguous. Some of the most common 
errors for users with a UNIX background are: 


- Only a single create at a time may be active per device. 


- File size is set by the first create and close-sequence; use lseek( i to ensure 
a specific file size; there is no append function to-‘expand.a file: ' 


- Files are strictly block oriented; unused ‘portions: of.a block.are filled: with: 
NULLs — there is no end-of-file marker other than the last block. ©: > 


locTL FUNCTIONS 
The Vx960 RT-11 file systein sapped the following ioctl() functions. The _ 
functions listed are definéd:in the header ioLib.h. Unless stated otherwise, 
the fd used for these functions may be any fd which is open to a file or to the 
volume itself. 


FIODISKFORMAT 
- Formats the entire disk with appropriate hardware track 
and sector marks. No file system is initialized on the disk 
by this request. Note that this is a driver-provided func- 
tion: 
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fd = open ("“DEV1:", WRITE); 
status = ioctl (fd, FIOOLSKFORMAT) ; 


FIODISKINIT - Initializes an RT-11 file system on the disk volume. This 
routine does not format the disk; formatting must be done 
by the driver. The fd should be obtained by opening the 
entire volume in raw mode: 


fd = open ("“DEV1:", WRITE); 
status = ioctl (fd, FIODISKINIT) ; 


FIODISKCHANGE 
- Announces a media change. It performs the same func- 
tion as rti1FsReadyChange(). This function may be 
called from interrupt level: 


status = loctl (fd, FPIODISKCHANGE) ; 


FIOGETNAME- Gets the file name of the fd and copies it to the buffer 
nameBuf,: . 


status = ioctl (fd, FIOGEITMAME, &nameuf); 


FIORENAME - Renames the file to the string newname: 
status = ioctl (fd, FIORENMAME, “newname"); 


FIONREAD __ - Copies to unreadCount the number.of unread bytes in the 
file: 
status = ioctl (fd, FIOSREAD, &unreadCount) ; 


FIOFLUSH _ - Flushes the ‘filé output buffer. It guarantees that any out- 
- | put that has been requested is actually written to the dev- 
ice. | | 


. status = loctl (fd, FIO?LUSE); 
FIOSEEK - Sets the current byte offset in the file to the position speci- 
fied by newOffset: 


status = ioctl (fd, FIOSEEK, newOffset); 


FIOWHERE _ - Returns the current byte position in the file. This is the 
byte offset of the next byte to be read or written. It takes 
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FIOSQUEEZE 


FIODIRENTRY- 


FIOREADDIR - 


FIOFSTATGET - 


no additional argument: 
position = loctl (fd, FIOWHERE); 


- Coalesces fragmented free space on an RT-11 volume: 


status = ioctl (fd, FIOSQUEEZE); 


Copies information about the specified directory entries to 
a REQ_DIR_ENTRY structure that is defined in ioLib.h. 
The argument req is a pointer to a REQ DIR_ENTRY 
structure. On entry, the structure contains the number of 
the directory entry for which information is requested. 
On return, the structure contains the information on the 
requested entry. For example, after the following: 


REQ DIR _EWTRY req; 
req.entryNum = 0; 
status = ioctl (fd, FIODIRENTRY, é&req) ; 


the request structure contains the name, size, and creation 
date of the file in the first entry (0) of the directory. 


Reads the next directory entry. The argument dirStruct is 
a DIR directory descriptor. Normally, the readdir() rou- 
tine is used to read a directory, rather than using the 
FIOREADDIR function directly. See dirLib. 


DIR dirStruct; 


fd = open (“directory”, READ); 
status = ioctl (fd, FIOREADDIR, &dirStruct); 


Gets file status information (directory entry data). The 
argument statStruct is a pointer to a Stat structure that is 
filled with data 


NAME 


rt11FsDevInit( ) - initialize the RT-11 device descriptor 
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SYNOPSIS 
RT_VOL_DESC ‘*xtllFsDeviInit (devName, pBlkDev, rtliFmt, nEntries, changeNoWarn) 

char wdevitesssj /* devices name */ 

BLK DEV *palkDev; /* pointer to block device info */ 

BOOL, xtlirmt) /* TRUE if RE-11 skew & interleave */ 

int ' nEntries; /* no. of dir entries incl term entry */ 

BOOL changeNoWarn; /* TRUE if no disk change warning */ 
DESCRIPTION 


This routine initializes the device descriptor. The pBlkDev parameter is a 
pointer to an already-created BLK_DEV device structure. This structure 
contains definitions for various aspects of the physical device format, as 
well as pointers to the sector read, sector write, tocti(), status check, and 
reset functions for the device. 


The rt11Fmt parameter is TRUE if the device is to be accessed using standard 
RT-11 skew and interleave. 


The device directory will consist of one segment able to contain at least as 
many files as specified by mnEntries. If nEntries is equal to 
RT_FILES FOR_2_BLOCK_SEG, strict RT-11 compatibility is maintained. 


The changeNoWarn parameter is TRUE if the disk may be changed without 
announcing the change via rt11FsReadyChange( ). Setting changeNoWarn to 
TRUE causes the disk to be regularly remounted, in case it has been 
changed. This results in a significant performance penalty. 


NOTE © 
An ERROR will be returned if rf11Fmt is TRUE .and the bd_blksPerTrack 
(sectors per track) field in the BLK_DEV structure is odd: This isbecause an © 
odd number of sectors per track is ‘incompatible with-the RT-11 interleaving | 
algorithm. 


RETURNS 
A pointer to the volume licncsicie (RT_VOL_DESC), or NULL: if alee rN, 
device parameters were specified, or the routine runs out of memo. | 


SEE ALSO 
rt11FsLib 
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NAME 
rt11FsInit( ) - prepare to use the RT-11 library 


SYNOPSIS 
STATUS rtllFsiInit (maxFiles) 
int maxFiles; /* maximum number of simultaneously */ 
/* open RT-11 files = */ 


DESCRIPTION 
This routine initializes the RT-11 library. It must be called exactly once, 
before any other routine in the library. The maxFiles parameter specifies the 
number of RT-11 files that may be open at once. This routine initializes the 
necessary memory structures and semaphores. 


To enable this initialization, define INCLUDE_RTIIFS in configAILh; 
rt11FsInit({) will then be called from the root task, usrRoot(), in 
usrConfig.c. 


RETURNS 
OK, or ERROR if memory is insufficient. 


SEE ALSO 
rtl1FsLib 


NAME 


rt11FsMkfs( ) - initialize a device and create an RT-11 file system 


SYNOPSIS 
RT _VOL_DESC *rtllFekkfs (voltame, pBlkDev) 
char *volName; /* volume name to use */ 
BLK DEV ‘pBlkDev; /* pointer to block device struct */ 
DESCRIPTION | 
This routine provides a quick method of creating an RT-11 file system on a 
device. It is used instead of the two-step procedure of calling 


rt11FsDevInit( ) followed by an ioctl() call with an FIODISKINIT function 
code. 


This routine provides defaults for the RT-11 parameters expected by 
rt11FsDevInit{ ). The directory size is set to RT_FILES FOR_2 BLOCK SEG 


1-294 Intel | Rev: 29 Aug 91 


 Upraties @) FELLESLib © 


(defined in rtl1FsLib.h). No standard RT-11 disk format is assumed; this 
allows use of RT-11 on block devices with an odd number of sectors per 
track. The ‘‘“changeNoWarn” flag is defined as false, indicating that that the 
disk will not be replaced without an rt11FsReadyChange( ) being called first. 


If different values are needed for any of these parameters, the routine 
rt11FsDevInit({ ) must be used instead of this routine, followed by a request 
for disk initialization using the ioctl( ) function FIODISKINIT. 


RETURNS 
A pointer to an RT-11 volume descriptor (RT_WOL_DESC), or NULL if there 
is an error. 


SEE ALSO 
rtl1FsLib 


NAME 
rt11FsDateSet{ ) - set the current date 


SYNOPSIS 
VOID rtllFsDateSet (year, month, day) 
int year; /* year (72...03 (RT-1l1’s dsys are numbered)) */ 
int month; /* month (0, or 1...12) */ 
int day; /* day (0, or 1...31) */ 


DESCRIPTION : 
This routine sets the current date for the RT-11 file system. All files created 
will have this creation date. 


To set a blank date, invoke the command: 
rtllFsDateSet (72, 0, 0); /* a date outside RT-11's epoch * 


RETURNS 
N/A 


SEE ALSO 
rt11FsLib 
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NAME 


rt11FsReadyChange( ) - notify rt11FsLib of a change in ready status 


SYNOPSIS 


VOID rtlirsReadyChange (vdptr) 
RT_VOL_ DESC ‘vdptr; /* pointer to device descriptor 


DESCRIPTION 
This routine sets the volume descriptor state to 
RT_VD_READY_CHANGED. It should be called whenever a driver senses 
that a device has come on-line or gone off-line (e.g., a disk has been inserted 
or removed). 


RETURNS 
N/A 


SEE ALSO 
rt11FsLib 
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NAME 
rt11FsModeChange( ) - modify the mode of an RT-11 volume 


SYNOPSIS 


VOID rtllFsModeChange (vdptr, newhode) | 
RT _VOL_DESC ‘*vdptr; /* pointer to volume descriptor “/ 
int newMode; /* READ/WRITE/UPDATE (both) */ 


DESCRIPTION 
This routine sets the volume descriptor mode to newMode. It should be 
called whenever the read and write capabilities are determined, usually after 
a ready change. See the manual entry for rt11FsReadyChange( ). 


The rt11FsDevInit( ) routine initially sets the mode to UPDATE, (e.g., both 
READ and WRITE). 


RETURNS 
N/A 
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SEE ALSO 
rt11FsLib 
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NAME 
scsiLib - Small Computer System Interface (SCSI) library 


SYNOPSIS 
scsiPhysDevDelete( ) - delete a SCSI physical device structure 
scsiPitysDevCreate( ) - create a SCSI physical device structure 
scsiPhysDevIdGet{ ) - return a pointer to a SCSI physical device structure 
scsiAutoConfig{ ) - configure all devices connected to a SCSI controller 
scsiShow( ) - list the physical devices attached to a SCSI controller 
scsiBlkDevCreate{ ) - define a logical partition on a SCSI block device 
scsiBlkDevInit{ ) - initialize fields in a SCSI logical partition 
scsiBusReset ( ) - pulse the reset signal on the SCSI bus 
scsiTestUnitRdy( ) - issue a TEST_UNIT_READY command to a SCSI device 
scsiFormatunit( ) - issue a FORMAT_UNIT command to a SCSI device 
scsilnguiry() - issue an INQUIRY command to a SCSI device 
scsiModeSelect{ ) - issue a MODE SELECT command to a SCSI device 
scsiModeSense ( ) - issue a MODE SENSE command to a SCSI device 
scstReadCapacity( ) - issuea READ_CAPACITY command to a SCSI device 
scsiRdSecs() - read sectors from an SCSI block device 
scsiWrtSecs( ) - write sectors to an SCSI block device 


scsiRegSense() - issue a REQUEST SENSE command to a device and read the result 


scsiloctl( ) - perform a device-specific control function 


STATUS scsiPhysDevDelete (pScsiPhysDev) 

SCSI_PHYS DEV *sceiPhysDevCreate (pScsiCtrl, devBusId, devlLlN, selTimeOdut, 
SCSI_PHYS DEV * scaiPhysDevIdGet (pScsiCtrl, devBusId, devLUM) ... 
STATUS scsiAutoConfig (pScsiCtrl, selTimeOut) ... 

STATUS scaiShow (pScsiCtr]l) 

BLK DEV *scsi8lkDevCreate (pScsiPhysDev, numBlocks, blockOffset) 

VOID scsiBlkDevInit (pScsiBlkDev, blksPexrTrack, nHeads) 

STATUS scsiBusReset (pScsiCtrl) 

STATUS sceiTestUnitRdy (pScsiPhysDev) 


STATUS scsiFormatUnit (pScsiPhysDev, cmpDefectList, defListFormat, vendorUnique, 


STATUS scaiInquiry (pScsiPhysDev, buffer, bufLength) 


STATUS scsidModeSelect (pScsiPhysDev, pageFormat, saveParams, buffer, bufLength) 
STATUS scsiModeSense (p6csiPhysDev, pageControl, pageCode, buffer, bufLength) 


STATUS scaiReadCapacity (pScsiPhysDev, plLastLBA, pBlkLength) . 
STATUS scsaiRkdsSecs (p&csiBlkDev, sector, numSecs, buffer) 
STATUS scsiWrtSecs (pSceiBlkDev, sector, num§ecs, buffer) 
STATUS scsiRegSenze (p&csiPhysDev, buffer, bufLength) 

STATUS scailoctl (p&csiPhysDev, function, arg) 
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DESCRIPTION 
This library implements the SCSI protocol in a controller-independent 
manner. It implements only the SCSI initiator function, so that the concept 
of a Vx960 target acting as a SCSI target is not currently supported. Further- 
more, in the current implementation, a Vx960 target is assumed to be the 
only initiator on the SCSI bus, although there may be — — _— 
peripherals) on the bus. 


The implementation is transaction based. A transaction is defined as the 
selection of a SCSI device by the initiator, the issuance of a SCSI command, 
and the sequence of data, status, and message phases necessary to perform 
the command. Normal completion ends with a ‘‘Command Complete” mes- 
sage from the target, followed by disconnection from the SCSI bus. In addi- 
tion, if the status from the target is ‘““Check Condition’, the transaction con- 
tinues with the initiator issuing a ““Request Sense’ command to gain more 
information on the exceptional condition reported. 


Many of the subroutines in scsiLib facilitate the transaction of frequently 
used SCSI commands. Individual command fields are passed as arguments 
from which SCSI Command Descriptor Blocks are constructed, and fields of 
a SCSI] TRANSACTION structure are filled in appropriately. This structure, 
along with the SCSI_ PHYS DEV structure associated with the target SCSI 
device, are passed to the routine whose address is indicated by the 
scstTransact field of the SCSI CTRL structure associated with the relevant 
SCSI controller. 


The function variable scsiTransact is set by the individual SCSI controller 
“driver.” Typically, for off-board SCSI controllers this routine would rear- 
range the fields of the SCSI_TRANSACTION structure into a similar struc- 
ture for the given hardware, which would then carry out the transaction 
through firmware control. Drivers for on-board SCSI controller chips can 
use the scsiTransact{ ) routine in scsiLib, as long as they provide the other 
functions specified in the SCSI_CTRL structure. The subject of interfaces 
between scsiLib and drivers for SCSI controllers will be addressed in a 
separate application note. 


NOTE: Disconnect /reconnect is not currently supported. 


SUPPORTED SCS! DEVICES 

SCSI peripherals conforming to the standards specified in “Common Com- 
mand Set (CCS) of the SCSI,” Rev. 4.B. are strongly recommended. Most 
SCSI peripherals currently offered support CCS. While an attempt has been 
made to have scsiLib support non-CCS peripherals, not all commands or 
features of this library are guaranteed to work with them. For example, 
auto-configuration may be impossible with non-CCS devices if they do not 
support the INQUIRY command. 
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In theory, all classes of SCSI devices are supported. The scsiLib library pro- 
vides the capability to transact any SCSI command on any SCSI device 
through the FIOSCSICOMMAND function of the scsiIoctl() routine. 


Only direct-access devices (disks) are supported by a file system. For other 
types of devices, additional, higher-level software is necessary to map user- 
level commands to SCSI transactions. — 


CONFIGURING SCSI CONTROLLERS 


The routines to create and initialize a given SCSI controller are specific to the 
controller and normally will be found in its library module. The normal cal- 
ling sequence is: 

xxCtrlCreate (...); /* parameters are controller specific * 

xxCtrlInit (...); /* parameters are controller specific * 


The conceptual difference between the two routines is that xxCtrlCreate( ) 
calloc()s memory for the XX_SCSI_CTRL data structure and initializes 
information that is never expected to change (e.g., clock rate). xxCtrlInit( ) 
initializes the remaining fields in the XX_SCSI_CTRL structure and writes 
any necessary registers on the SCSI controller to effect the desired initializa- 
tion. There is no reason this routine could not be called multiple times, 
although in practice this would probably occur infrequently. For example, 
one might wish to change the bus ID of the SCSI controller without reboot- 
ing the Vx960 system. 


CONFIGURING PHYSICAL SCSI DEVICES 


Before a device can be used, it must be “created”’ (i.e., declared). This occurs 
with a call to scsiPhysDevCreate(), and can only be done after a 
SCSI_CTRL structure exists and is properly initialized. 


SCSI_PHYS DEV *scsiPhysDevCreate (p&csiCtrl, devBusId, devLUN, caiviassie, 
devType, removable, numBlocks, blockSize) 
SCSI_CYRL *p@csaiCtrl; /* ptr to SCSI controller info * 
int devBusId; /* device’s SCSI bus ID * 
int devitm; /* device’s logical unit number * 
UINT selTimeOut; /* time-out for selecting device (usec) * 
int devType; /* type of SCSI device * 
BOOL removable; /* whether medium is removable * 
int numBlocks; /* number of blocks on device * 
int blockSize; /* size of a block in bytes * 


several of these parameters may be left unspecified as follows: 
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selTimeOut 
- If 0, use the default (250 msec) 


devlT ype 
- If -1, issue an INQUIRY to determine 


numBlocks, 
- If 0, issue a READ CAPACITY to determine 


The above values are recommended unless the device does not support the 
required commands or other non-standard conditions prevail. 


LOGICAL PARTITIONS ON BLOCK DEVICES 
It is possible to have more than one logical partition on a SCSI block device. 
This capability is currently not supported for removable media devices. A 
partition is simply an array of contiguously-addressed blocks with a given 
starting block address and number of blocks. The _ routine 
scsiBlkDevCreate() should be called once for each block device partition. 
Under normal usage, logical partitions should not overlap. 


SCSI_BLK_DEV “scsiBlkDevCreate (p&csiPhysDev, numBlocks, blockOffset ) 
SCSI_PHYS DEV *pScsiPhysDev; /* ptr to SCSI physical device info * 
int numBlocks; /* number of blocks in block device * 
int blockOffset; /* address of first block in volume * 


NOTE: If numBlocks is 0 the rest of device is used. 


ATTACHING FILE SYSTEMS TO LOGICAL PARTITIONS 
Before files can be read or written to a disk partition, a file system (e.g., RT- 
11, MS-DOS) must be initialized on it. See the manual entries for rt11FsLib 
or dosFsLib. 7 


TRANSACTING ARBITRARY COMMANDS TO SCSI DEVICES 
The scsiLib library provides routines which implement many common SCSI 
commands. Still, there are situations that require commands that are not 
supported by scsiLib (e.g., control devices that are not direct access dev- 
ices). Arbitrary commands are handled with the FIOSCSICOMMAND 
option to scsiloctl( ). The arg parameter for this option is a pointer to a valid 
SCSI_TRANSACTION structure. 


Typically, a call to scsiIoctl( ) is written as a subroutine of the form: 


STATUS myScsiConmmand (pécsiPhysDev, buffer, bufLength, someParan) 
SCSI_PHYS DEV *p6csiPhysDev;/* ptr to SCSI physical device * 
char *buffer; /* ptr to data buffer * 
int bufLength; /* length of buffer in bytes * 
int someParam; /* parameter specifiable in and block * 


{ 
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SCSI_ COMMAND myScsiCadBlock; /* SCSI command byte array * 
SCSI_TRAMSACTION myScsixXaction; /* info on a SCSI transaction * 


/* £i11 in fields of SCSI_COM@MD structure * 
myScsiCadBlock [0] = MY_COMMAND OPCODE; /* the required opcode * 


myScsiCadBlock [X]) = (UINTS) someParam; /* for example * 


myScsiCadBlock [H-1l] = MY CONTROL BYTE; /* typically == 0 * 
/* #111 in fields of SCSI_TRANSACTION structure * 


my3csixaction.cadAddress = my8csiCadBlock; 
myScsixaction.cndLength = <# of valid bytes in myScsiGadBlock>; 
myicaiXaction.dataAddress = (UINTS *) buffer; 
myScsixaction.dataDirection = <READ (0) or WRITE (1)>; 
myScsixaction.dataLength = bufLength; 


/* if dataDirection is READ, and the length of the input data is 

* variable, the following parameter specifies the byte # (min == 0) 
* of the input data: Ss will specify the additional number of 

* bytes available 


® 


myScsixaction.addLengthByte = X; 


if (scsiloctl (peceiPhysDev, FIOGCSICOMMAND, &myScsiXaction) == OK) 
return (CX); | 

else 

/* optionally perform retry or other action based on value of 

* epee ern aee ere | | 
Sd 
return (ERROR); 

} 


INCLUDE FILES 
- scsiLib.h 


SEE ALSO 
-TtLIFsLib, dosFsLib; Sindee’ Guide: I/O System 
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NAME 
scsiPhysDevDelete( ) - delete a SCSI physical device structure 


SYNOPSIS 
STATUS scsiPhysDevDelete (pScsiPhysDev) 
SCSI_PHYS DEV ‘“pécsiPhysDev; /* ptr to SCSI physical device info */ 


RETURNS | 
OK, or ERROR if pScsiPhysDev is NULL, or if SCSI block devices have been 


created on the device. 


SEE ALSO 
scsiLib 


NAME 
scsiPhysDevCreate( ) - create a SCSI physical:device structure-- - 


SYNOPSIS 
SCSI_PHYS DEV “scsiPhysDevCreate (pScsiCtri; devBusId;-devLUM ;:.selTimsOut;.- i <-> 
devType, removable, numBlocks, blockSize). 


SCSI_CTRL ‘*pScsiCtrl; /* ptr to SCSI: controller info: das gt le ap ee eee: 
int — davBusid; /* device’s SCSI bus ID-+/. . pe mmateegs ye 
int devLUN; /* device’s -_logical inte aes “al; cae Og Rad a PR ora 
UINT melTimeOut; /* time-out for selecting.’ ‘Bavice, faaeeae tf cab.:fost. 228 
int devType; /* type of SCSI davice:#/<+ ftagpa ed SSX aay 
BOOL renovable; /* whether mediua ay war whet nage mand seg, 5 
int -; numBlocks ; /* number of- blocks on-device:*/ 74 =e5.5 of bic. 
int blockSize; /* gise of a-block in bytes: */-: f2 adss ag & Biaeh 
DESCRIPTION | 
This routine must be vked before a “scsi device can be accesseth alt eet 
should be called once for each physical device on the SCSI bus... °°... nent 3 


If devType is specified as NONE (-1), an INQUIRY ieaiaiea eat (Oo 
determine the device type, with the added benefit of acquiring the make and- : +:.-->~; 
model number (scsiShow( ) displays this information). Common values of 
devType can be found in scsiLib.h or the SCSI specification itself. 
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NOTE 
If a SCSI device does not support the READ CAPACITY command, then 
numBlocks and blockSize must be non-zero. 


RETURNS | 
A pointer to the created SCSI_PHYS_DEYV, or NULL if the routine is unable 


to create a physical device. 


SEE ALSO 
scsiLib 


NAME 
scsiPhysDevIdGet{ ) - return a pointer to a SCSI physical device structure 


SYNOPSIS 
SCSI PHYS DEV * scsaiPhysDevIdGet (pScsiCtrl, devBusId, devLUN) 
SCSI_CYRL ‘*pScsiCtrl; /* ptr to SCSI controller info */ 


int devBusId; /* device’s SCSI bus ID */ 
int devLUN; /* device’s logical unit number */ 
DESCRIPTION 


This routine returns a pointer to the structure SCSI_PHYS_DEV of the SCSI 
physical device at the given bus ID, logical unit number, and SCSI controller. 


RETURNS 
A pointer to the structure SCSI_ PHYS _ DEV or NULL if the structure does 


not exist. 


SEE ALSO 
scsiLib 


NAME 
scsiAutoConfig( ) - configure all devices connected to a SCSI controller 


SYNOPSIS 
STATUS scsiAutoConfig (pScsiCtrl, selTimeOut) 
SCSI_CTRL ‘*pScsictrl; /* ptr to SCSI controller info */ 
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UINT selTimeOut; /* time-out for selecting devices (usec) */ 


DESCRIPTION 
This routine cycles through all legal SCSI bus IDs (and LUNs) and calls 
scsiPhysDevCreate( ) with default parameters for each device. All devices 
that support the INQUIRY command should be successfully configured. 
The scsiShow() command can be used to find the system's table of the SCSI 
physical devices attached to a given SCSI controller. In addition, 
scsiPhysDevIdGet{ ) can fetch a pointer to the SCSI_PHYS_DEV structure 
- for the device at a given SCSI bus ID and LUN. 


RETURNS 
OK, or ERROR if pScsiCtrl and pSysScsiCtrl are both NULL. 


SEE ALSO 
scsiLib 


NAME 


scsiShow( ) - list the physical devices attached to a SCSI controller 


— SYNOPSIS 
STATUS scsiShow (pScsiCtr]) 
SCSI_CTRL ‘“pécsictrl; /* ptr to SCSI controller info */ 


DESCRIPTION 
This routine displays the SCSI bus ID, logical unit number (LUN), vendor 
ID, product ID, firmware revision (rev.), device type, number of blocks, 
block size (bytes), and a pointer to the associated SCSI_PHYS_DEV struc- 
ture for each i SCSI device known to be attached to a given SCSI 
controller. 


NOTE: If psesiCtrl i is NULL, the value of the _ variable pSysScsiCtrl will 
be used, unless itis also NULL. 


RETURNS | 
OK, or ERROR if the routine is not successful. 


SEE ALSO 
scsiLib 
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NAME 
scsiBlkDevCreate( ) - define a logical partition on a SCSI block device 


SYNOPSIS 
BLK DEV *scsiBlkDevCreate (pécsiPhysDev, numBlocks, blockOffset) 
SCSI_PHYS DEV ‘*pScsiPhysDev; /* ptr to SCSI physical device info */ 


int : numBlocks ; /* number of blocks in block device */ 
int blockOffset ; /* address of first block in volume */ 
DESCRIPTION 


This routine creates and initializes a BLK_DEV structure, which describes a 
logical partition on a SCSI physical block device. A logical partition is an 
array of contiguously addressed blocks; it can be completely described by 
the number of blocks and the address of the first block in the partition. In 
normal configurations, partitions do not overlap, although such a condition 
is not an error. 


NOTE: If numBlocks is 0, the rest of device is used. 


RETURNS 
A pointer to the created BLK_DEV, or NULL if a partition is not created. 


SEE ALSO 
scsiLib 
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NAME 
scsiBlkDevInit )- initialize fields in;a. SCSI logical partition 


SYNOPSIS 
VOID scsiBlkDevInit (pScsiBlkDev, blksPerTrack, nHeads) 
SCSI_BLK DEV ‘“pGcsiBlkDev; /* ptr ‘to SCSI block dev. struct */ 


<a t. 


int blksPerTrack; /* blocks. per track */- 
int — nHeads ; /* number of heads */ 
DESCRIPTION 


This routine specifies the disk geometry parameters that are required by 
some file systems (e. g-, dosFs). It should be called after a SCSI_BLK_DEV 
structure is created via scsiBlkDevCreate( ), but before any file system ini- 
tialization routine. It is generally required only for removable media 
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devices. 
RETURNS 
N/A 
SEE ALSO 
scsiLib 
— _ oF oo. 
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NAME 
scsiBusReset ( ) - pulse the reset signal on the SCSI bus 


SYNOPSIS 
STATUS scsiBusReset (pScsiCtrl) 
SCSI CTRL ‘“pScsiCtrl; 


DESCRIPTION 
This routine calls a controller-specific routine to perform a SCSI bus reset. If 
no controller is specified (pScsiCtrl is 0), the value in pSysScsiCtrl is used. 


RETURNS 
OK if a controller-specific routine exists, or ERROR otherwise. 


SEE ALSO 
scsiLib 


NAME : | : 
scsiTestUnitRdy( ) - issue a TEST_UNIT_READY command to a SCSI device:. © 


SYNOPSIS 
STATUS scaiTestUnitRdy (p&ScsiPhysDev) 
SCSI_PHYS DEV ‘*p&csiPhysDev; /* ptr to SCSI physical device “/ 


RETURNS 
- OK, or ERROR if the fouline is not successful. 


SEE ALSO 
scsiLib 
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NAME | 
scsiFormatUnit( ) - issue a FORMAT _UNIT command to a SCSI device 


SYNOPSIS | 
STATUS scsiFormatUnit ec ata cupDefectList, defListFormat, vendorUnique, 
interleave, buffer, bufLength) 
SCSI_PUYS DEV ‘*pécaiPhysDev; /* ptr to SCSI physical device */ 


BOOL cupDefectList; /* whether defect list is complete */ 
int defListFormat; /* defect list format */ 
int vendorUnique; /* vendor unique byte 
int interleave; /* interleave factor */ 
char thuffer; /* per to input data buffer */ 
int bufLength; /* length of buffer in bytes 
RETURNS 
OK, or ERROR if the routine is not successful. 
SEE ALSO 
scsiLib 
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NAME 
scstInguiry() - issue an INQUIRY command to a SCSI device 


SYNOPSIS 


STATUS scaiInquiry (pécsiPhysDev, buffer, bufLength) 
SCSI_PHYS DEV ‘pécsiPhysDev; /* ptr to SCSI physical device */ 


char *buffer; /* per to input data buffer */ 
int bufLength ; /* length of buffer in bytes */ 
RETURNS 
OK, or ERROR if the routine is not successful. 
SEE ALSO 
scsiLib 
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NAME 


scsiModeSelect{ ) - issue a MODE SELECT command to a SCSI device 


SYNOPSIS 
STATUS scsidodeSelect (p&écsiPhysDev, pageFormat, saveParams, buffer, bufLength) 
SCSI_PHYS DEV ‘*p&ScsiPhysDev; /* ptr to SCSI physical device */ 


int pageFormat ; /* value of the page format bit (0-1) */ 
int saveParams} /* value of the save parameters bit (0-1) */ 
char *buffer; /* per to output data buffer */ 
int bufLength ; /* length of buffer in bytes 
RETURNS 
OK, or ERROR if the routine is not successful. 
SEE ALSO 
scsiLib 
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NAME 
scsiModeSense( ) - issue a MODE SENSE command to a SCSI device 


SYNOPSIS 
STATUS scsidodeSense (pécsiPhysDev, pageControl, pageCode, buffer, bufLength) 
SCSI_PHYS DEV ‘p6csiPhysDev; /* ptr to SCSI physical device */ 


int pageControl; /* walue of the page control field (0-3) */ 
int pageCode; /* value of the page code field (0-Ox3f) */ 
char *buf fer; /* per to input data buffer */ 
int bufLength ; /* length of buffer in bytes 
RETURNS 
OK, or ERROR if the routine is not successful. 
SEE ALSO 
scsiLib 
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NAME 
scstReadCapacity( ) - issue a READ_CAPACITY command to a SCSI device 


SYNOPSIS 
STATUS scaiReadCapacity (pécsiPhysDev, plastLBA, p&lkLength) 
SCSI_PHYS DEV ‘“pGcsiPhysDev; /* ptr to SCSI physical device */ 
int *pLast LBA; /« where to return last logical block address | 
int *palkLength ; /* where to return block length * 


RETURNS 
OK, or ERROR if the routine is not successful. 
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NAME 
scsiRdSecs() - read sectors from an SCSI block device 


SYNOPSIS 
STATUS scsiRkdSecs (p&csiBlkDev, sector, nunSecs, buffer) 
SCSI_BLK DEV ‘*p&csiBlkDev; /* ptr to SCSI block device info */ 
int sector } /* sector number to be read */ 
int numGecs } /* sector number to be read */ 
char *buf fer} /* ptr to input data buffer */ -- , 


DESCRIPTION... DesCuie:| 
_ This routine reads the specified physical sectors from: the: specified: physicat 
device. 


RETURNS 
OK, or ERROR if the routine is not successful. 


SEE ALSO 
scsiLib 
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NAME 
scstWrtSecs() - write sectors to an SCSI block device 


SYNOPSIS : 
STATUS scaiWrtSecs (pécsiBlkDev, sector, numGecs, buffer) 
SCSI_BLK DEV ‘pScsiBlkDev; /* ptr to SCSI block device info */ 


int sector; /* sector number to be read */ 
int numGecs; /* sector number to be read */ 
char *buf fer; /* ptr to input data buffer */ 


DESCRIPTION 
This routine writes the specified physical sectors to the specified physical 
device. 


RETURNS 
OK, or ERROR if the routine is not successful. 


SEE ALSO 
scsiLib 


NAME 
scsiRegSense() - issue a REQUEST-SENSE command: to a-device and read 


the results 


SYNOPSIS beech, 
STATUS scsiReqSense eessivivscers cbuffer, nbufLength).s.6:-si6h 0 ew ee 
SCSI_| PHYS_DEV *p&csiPhysDev; /* ptr to SCSI physical device */ 
chart tbhuffer; /* per to input data buffer */ 
int bufLength; /* length of buffer in bytes * 


RETURNS 
OK, or ERROR if the routine is not successful. 


SEE ALSO 
scsiLib 
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NAME 
scsiloctl( ) - perform a device-specific control function 


SYNOPSIS ee. 
STATUS scsilIoctl (pécsiPhysDev, function, arg) 
SCSI_PHYS DEV ‘*pécsiPhysDev; /* ptr to SCSI block device info */ 


int function; /* function code */ 
int arg; /* argument to pass called function */ 
RETURNS 
The status of the request, or ERROR if the request is unsupported. 
SEE ALSO 
scsiLib 
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selectLib - UNIX BSD 4.3 select library 


SYNOPSIS 


selectInit( ) - initialize the select() library 

select() - pend ona set of file descriptors 

selWakeup( ) - wake up a task pended in select( ) 

selWakeupAll( ) - wake up all tasks on a select() wake-up list 

selNodeA dd({ ) - add a wake-up node to the select() wake-up list 
selNodeDelete( ) - find and delete a node on a wake-up list 
selWakeupListInit{ ) - initialize a select( ) wake-up list 
selWakeupListLen( ) - get the number of nodes on a select() wake-up list 
selWakeupType( ) - get the type of the given SEL_WAKEUP_NODE 


VOID selectInit () 

int select (width, pReadFds, pWriteFds, pExceptFds, pTimeOut) 
VOID selWakeup (pWakeupNode) 

VOID selWakeupAll (pWakeupList, type) 

STATUS selNodeAdd (pWakeupList, pWakeupiiode) 

STATUS selNodeDelete (pWakeupList, pWakeupNode) 

VOID selWakeupListInit (pWakeupList) 

int selWakeupListLen (pWakeupList) 

SELECT TYPE selWakeupType (pWakeupNode) 


DESCRIPTION : 


This library provides a BSD 4.3 compatible select facility to wait for activity 
on a set of file descriptors.. The select() routine uses a set of routines that 
permits tasks pended on device activity to be detected by the device’s 
driver. Thus, the driver's interrupt service routine directly wakes up such 
tasks, eliminating the need for polling. 


Applications can use select() with pipes and serial devices in addition to 
sockets. Also, select() examines write file descriptors in addition to read file 
descriptors; however, exception file descriptors are still unsupported. 


Typically, application developers need only concern themselves with the 
select() call. However, driver developers should become familiar with the 
other routines that may be used with select() if they wish to support the 
select() mechanism. 


SEE ALSO 


Programmer's Guide: I/O System 
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NAME | 
selectInit( ) - initialize the select( ) library 
SYNOPSIS 
VOID selectIinit 0 
DESCRIPTION 


This routine initializes the select() library. It should be called only once, 
and is typically called from the root task, usrRoot(), in usrConfig.c. It 
installs a task delete hook that cleans up after a task if the task is deleted 
while pended in select( ). 


RETURNS 
N/A 


SEE ALSO 
selectLib 
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NAME 
select( ) - pend on a set of file descriptors 
SYNOPSIS 
int select (width, pReadFds, pWriteFds, pExceptFds, pTimeOut). 
int width; /* number-of bits to examine from 0 «/ 
fd_set *pReadFds; /* vead file descriptors .*/ 
fd set - speiriterds; /*.write: file-:descriptors:*/..2 ee 
fd_set *pExceptFds; /* exception file descriptors */ 


struct timeval ‘*pTimeOut; /* maximum time to wait for activity; 
* WULL to wait forever */ 


DESCRIPTION 

This routine permits a task to pend until one of a set of file descriptors 
becomes ready. Three parameters — pReadFds, pWriteFds, and pExceptFds — 
point to fd sets in which each bit corresponds to a particular file descriptor. 

Bits set in the read fd set (pReadFds) will cause select() to pend until data is 
available on the any of the corresponding file descriptors, while bits set in 
the write fd set (pWriteFds) will cause select() to pend until any of the 
corresponding file descriptors become writable. (pExceptFds is currently 
unused, but is provided for UNIX call compatibility). 
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The following macros are available for setting the appropriate bits in the fd 
set structure: 


FD SET(fd, &fdset) 
FD CLA(fd, &fdset) 
FD ZSERO(&fdset) 


If either pReadFds or pWriteFds is NULL, they are ignored. The width parame- 
ter defines how many bits will be examined in the fd sets, and should be set 
to either the maximum fd value in use, or simply FD_SETSIZE. When 
select() returns, it zeros out the fd sets, and sets only the bits that 
correspond to file descriptors that are ready. The FD_ISSET macro may be 
used to determine which bits are set. | 


If pTimeOut is NULL, select() will block indefinitely. If pTimeOut is not 
NULL, but points to a timeval structure with an effective time of zero, the 
file descriptors in the fd sets will be polled, and the results returned immedi- 
ately. If the effective time value is greater than zero, select() will return 
after the given time has elapsed, even if none of the file descriptors are 
ready. 


Applications can use select() with pipes and serial devices in addition to 
sockets. Also, select() now examines write file descriptors in addition to 
read file descriptors; however, exception file descriptors are still unsup- 
ported. 


Driver developers should consult: the “1/O System” chapter of the Vx960- 


Programmer's Guide for details on writing drivers that will use select( ). 
Ree 


* The number of file dancionists withiactivity, 0 if timed out, or ERROR a an. 


error occurred when the driver's select():routine was invoked via toctl().' : 


SEE ALSO Ap a 
selectLib, Programmer's Guide: 0 System: + 
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NAME 
selWakeup( ) - wake up a task pended in select( ) 


SYNOPSIS 
VOID selWakeup (plakeuplode) | 
SEL WAKEUP NODE ‘pWakeupNode; /* node to awaken */ 
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DESCRIPTION 
After a driver's FIOSELECT function installs a wake-up node in a device's 
wake-up list (with selNodeAdd{)), it should check to see if the device is 
actually ready. If so, it should call sel{Wakeup( ) to ensure that the select( ) 
call does not pend. 


RETURNS 
N/A 


SEE ALSO 
selectLib 
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NAME 
selWakeupAll( ) - wake up all tasks on a select( ) wake-up list 


SYNOPSIS 
VOID selWakeupAll (pWakeupList, type) 
SEL_WAKEUP LIST ‘*pHakeupList; /* list of tasks to wakeup 
SELECT_TYP& type; /* wakeup readers (SELREAD), 
* or writers (SELWRITE) */ 


DESCRIPTION 
This routine is called by a driver when a device Becomes ready. It wakes up 
all tasks pended in select( ) that are waiting for this device. 


RETURNS 
N/A 


SEE ALSO 
selectLib 


NAME | 
selNodeAdd{ ) - add a wake-up node to the select( ) wake-up list 


SYNOPSIS 


STATUS sellodeAdd (pWakeupList, pWakeupiiode) 
SZL_WAKEUP LIST *pHakeupList; 
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SEL WAKEUP NODE ‘*pWakeuptiode; 


DESCRIPTION 
This routine should be called from a driver's FIOSELECT function to add a 
wake-up node to a device’s wake-up list. 


RETURNS 
| OK, or ERROR if memory is insufficient. 


SEE ALSO 
selectLib 
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NAME 
selNodeDelete( ) - find and delete a node on a wake-up list 


SYNOPSIS 
SYRTUS solWNodebelete (pWakeupList, pWekeupxode) 
SEL WAKEUP LIST *plWakeupList; 
SSL WAKEUP_MODE *pWakeupNode; 
DESCRIPTION 


_ This routine deletes the specified wake-up node from the given wake-up 
- list. It is typically called by a driver's FIOUNSELECT function. 


RETURNS 
OK, or ERROR if the node is not found in the wake-up list. 


SEE ALSO 
selectLib 


gine dceaties eS Ss eee SEES 


NAME 
selWakeupListinit{ ) - initialize a select( ) wake-up list 


SYNOPSIS | 
VOID selWakeupListInit (pWakeupList) 
SEL WAKEUP LIST *pWakeupList; 
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DESCRIPTION 
This routine should be called in a device's create routine to initialize the 
SEL_WAKEUP LIST structure. 


RETURNS 
N/A_ 


SEE ALSO 
selectLib 
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NAME | 
selWakeupListLen( ) - get the number of nodes on a select() wake-up list 


SYNOPSIS 
int selWakeupListLen (pWakeupList) 
SEL WAKEUP LIST ‘*pWakeupList; 


DESCRIPTION 
This routine can be used by a driver to determine if any tasks are currently 
pended in select() on this device, and whether these tasks need to be 
activated with selWakeupAll( ). 


RETURNS 7 
The number of nodes currently on a select( ) wake-up list, or ERROR other- 
wise. 


SEE ALSO 
selectLib 
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NAME 
selWakeupType( ) - get the type of the given SEL_WAKEUP_NODE 


SYNOPSIS 


SELECT TYPE selWakeupType (pWakeupNode) 
SEL_WAKEUP NODE ‘*pWakeupNode; 
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DESCRIPTION 
This routine is typically used in a device’s FIOSELECT function to determine 
if the device is being selected for read or write operations. 
RETURNS 
SELREAD (read operation) or SELWRITE (write operation). 
SEE ALSO 
selectLib 
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NAME 
semB Lib - binary semaphore library 


SYNOPSIS | 
semBCreate( ) - create and initialize a binary semaphore 


SEX ID semiCreate (options, initialState) 


DESCRIPTION 
This library provides the interface to Vx960 binary semaphores. Binary 
semaphores are the most versatile, efficient, and conceptually simple type of 
semaphore. They can be used to: (1) control mutually exclusive access to 
shared devices or data structures, or (2) synchronize multiple tasks, or task- 
level and interrupt-level processes. Binary semaphores form the foundation 
of numerous Vx960 facilities. 


A binary semaphore can be viewed as a cell in memory whose contents are 
in one of two states, full or empty. When a task takes a binary semaphore, 
using semTake( ), subsequent action depends on the state of the semaphore: 


(1) = If the semaphore is full, the semaphore is made empty, and the cal- 
ling task continues executing. 


(2) If the semaphore is empty, the task will be blocked, pending the avai- 
lability of the semaphore. If a timeout is specified and the timeout 
expires, the pended task will be removed from the queue of pended 
tasks and enter the ready state with an ERROR status. A pended task © 
is ineligible for CPU allocation. Any number of tasks may be pended 
simultaneously on the same binary semaphore. 


When a task gives a binary semaphore, using semGive(), the next available 
task in the pend queue is unblocked.. If no task is pending on this sema- 
phore, the semaphore becomes full. Note that if a semaphore is given, and a 
task is unblocked that is of higher priority than the task that called 
semGive(), the unblocked task will preempt the calling task. 


MUTUAL EXCLUSION | 
To use a binary semaphore as a means of mutual exclusion, first create it 
with an initial state of full. For example: 


SEM _ ID seritutex; 


/* create a binary semaphore that is initially full * 
sembtitex = semiCreate (SEQ PRIORITY, SEM_FULL)} 


Then guard any critical section or resource by taking the semaphore via 
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semTake( ), and exit the section or release the resource by giving the sema- 
phore via semGive(). For example: 


semTake (senttutex, WAIT _ FOREVER) ; 
. /* critical region, only accessible by a single task at a time * 


semGive (senitutex) ; 


While there is no restriction on the same semaphore being given, taken, or 
flushed by multiple tasks, it is important to ensure the proper functionality 
of the mutual-exclusion construct. While there is no danger in any number 
of processes taking a semaphore, the giving of a semaphore should be more 
carefully controlled. If a semaphore is given by task that did not take it, 
mutual exclusion could be lost. 


SYNCHRONIZATION 
To use a binary semaphore as a means of synchronization, create it with an 
initial state of empty. A task will block by taking a semaphore at a syn- 
chronization point and remain blocked until the semaphore is given by 
another task or interrupt service routine. 


Synchronization with interrupt service routines is a particularly common 
need. Binary semaphores can be given, but not taken, from interrupt level. 
Thus a task can block at a synchronization point via semTake(), and an 
interrupt service routine can unblock that task via semGive( ). 


In the following example, when init() is called, the binary semaphore is 
created, an interrupt service routine is attached to an event, and a task is 
spawned to process the event. Task1() will run until it calls semTake( ), at 
which point it will block until an event causes the interrupt service routine 
to call semGive(). When the interrupt service routine completes, task1() 
can execute to process the event. 


SEM ID semSync; /* ID of sync semaphore * 


init () 
{ 
intConnect (..., eventInterruptSvcRout, ...)} 
senGync = semBCreate (SEM_Q FIFO, SEM EMPTY); 
taskEpmm (..., taskl); 


} 
taskl () 
{ 
semTake (semSync, WAIT FOREVER) ; /* wait for event to oocur * 
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ee /* process event * 


eventinterruptSvcRout () 


semGive (semGync) ; /* let task 1 process event * 


A semFlush() on a binary semaphore will atomically unblock all pended 
tasks in the semaphore queue, i.e., all tasks will be unblocked at once before 
any actually execute. 


CAVEATS 


There is no mechanism to give back or reclaim semaphores automatically 
when tasks are suspended or deleted. Such a mechanism, though desirable, 
is not currently feasible. Without explicit knowledge of the state of the 
guarded resource or region, reckless automatic reclamation of a semaphore 
could leave the resource in a partial state. Thus if a task ceases execution 
unexpectedly, as with a bus error, currently owned semaphores will not be 
given back, effectively leaving a resource permanently unavailable. The 
mutual-exclusion semaphores provided by semMLib offer protection from 
unexpected task deletion. 


SEE ALSO 
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semLib, semCLib, semMLib, — Guide: Basic OS 
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semBCreate() - create and initialize a binary semaphore 


SYNOPSIS 


SEM ID senBCreate (options, initialState) 
int options; /* semaphore options */ 
SEM_B STATE initialstate; /* initial semaphore state */ 


DESCRIPTION 


This routine allocates and initializes a binary semaphore. The semaphore is 
initialized to the initialState of either SEM_ FULL (1) or SEM_ EMPTY (0). 


The options parameter specifies the queuing style for blocked tasks. Tasks 
can be queued on a priority basis or a first-in-first-out basis. These options 
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are SEM_Q_ PRIORITY and SEM_Q FIFO respectively. 


RETURNS 

The semaphore ID, or NULL if memory cannot be allocated. 
SEE ALSO 

semBLib 
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NAME 
semCLib - counting semaphore library 


SYNOPSIS a 
semCCreate( ) - create and initialize a counting semaphore 


SEM ID semCCreate (options, initialCount) 


DESCRIPTION 
This library provides the interface to Vx960 counting semaphores. Counting 
semaphores are useful for guarding multiple instances of a resource. 


A counting semaphore may be viewed as a cell in memory whose contents 
keep track of a count. When a task takes a counting semaphore, using 
semTake( ), subsequent action depends on the state of the count: 


(1) Ifthe count is non-zero, it is decremented and the calling task continues 
executing. 


(2) If the count is zero, the task will be blocked, pending the availability of 
the semaphore. If a timeout is specified and the timeout expires, the 
pended task will be removed from the queue of pended tasks and enter 
the ready state with an ERROR status. A pended task is ineligible for 
CPU allocation. Any number of tasks may be pended simultaneously 
on the same counting semaphore. 


When a task gives a semaphore, using semGive(), the next available task in 
the pend queue is unblocked. If no task is pending on this semaphore, the 
semaphore count is incremented. Note that if a semaphore is given, and a 
task is unblocked that is of higher priority than the task that called 
semGive( ), the unblocked task will preempt the calling task. 


A semFlush() on a counting semaphore will atomically unblock all pended 
tasks in the semaphore queue. So all tasks will be made ready before any 
task actually executes. The count of the Bemaphon will remain unchanged. 


INTERRUPT USAGE : 
Counting semaphores may be given but not taken from interrupt level. 


CAVEATS 
There is no mechanism to give back or reclaim semaphores automatically 
when tasks are suspended or deleted. Such a mechanism, though desirable, 
is not currently feasible. Without explicit knowledge of the state of the 
guarded resource or region, reckless automatic reclamation of a semaphore 
could leave the resource in a partial state. Thus if a task ceases execution 
unexpectedly, as with a bus error, currently owned semaphores will not be 


1 - 324 Intel Rev: 29 Aug 91 


Libraries (1) semCLib 


given back, effectively leaving a resource permanently unavailable. The 
mutual-exclusion semaphores provided by semMLib offer protection from 
unexpected task deletion. 


SEE ALSO 
semLib, semBLib, semMLib, Programmer's Guide: Basic OS 


NAME 
semCCreate() - create and initialize a counting semaphore 


SYNOPSIS 
SEM ID semCCreate (options, initialCount) 
int options; /* semaphore option modes */ 
int initialCount; /* initial count */ 


DESCRIPTION 
This routine allocates and initializes a counting semaphore. The semaphore 
is initialized to the specified initial count. 


The options parameter specifies the queuing style for blocked tasks. Tasks 
may be queued on a priority basis or a first-in-first-out basis. These options 
are SEM_Q_ PRIORITY and SEM_Q FIFO respectively. 


RETURNS “ _ 
The semaphore ID, or NULL if memory cannot be allocated. 


SEE ALSO 
semCLib 
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NAME | 
semLib - general semaphore library 


SYNOPSIS | 
semGive() - give a semaphore 
semTake( ) - take a semaphore 
semFlush() - unblock every task pended on a semaphore 
semDelete() - delete a semaphore 
semInfo() - get list of task IDs that are blocked on semaphore 


STATUS semGive (semId) 

STATUS semTake (semId, timeout) 
STATUS senFlush (senId) 

STATUS semDelete (semid) 

int semInfo (semId, idList, maxTasks) 


DESCRIPTION 
Semaphores are the basis for synchronization and mutual exclusion in 
Vx960. They are powerful in their simplicity and form the foundation for 
numerous Vx960 facilities. 


Different semaphore types serve different needs, and while the behavior of 
the types differs, their basic interface is the same. This library provides 
semaphore routines common to all Vx960 semaphore types. For all types, 
the two basic operations are semTake() and setnGive(), the acquisition or 
relinquishing of a semaphore. ‘ 


Semaphore creation and initialization is handled by other libraries, depend- 
ing on the type of semaphore used. These libraries contain full functional 
descriptions of the semaphore type: a 


semBLib  - binary semaphores 
semCLib -counting semaphores | 
semMLib - mutual exclusion semaphores | 


Binary semaphores offer the greatest speed and the broadest applicability. 


The semLib library provides all other semaphore operations, including rou- 
tines for semaphore control, deletion, and information. Semaphores must be 
validated before any semaphore operation can be undertaken. An invalid 
semaphore ID results in ERROR and an appropriate errno is set. 


SEMAPHORE CONTROL 
The semTake( ) call acquires a specified semaphore, blocking the calling task 
or making the semaphore unavailable. All semaphore types support a 
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timeout on the semTake( ) operation. The timeout is specified as the number 
of ticks to remain blocked on the semaphore. Timeouts of WAIT_FOREVER 
and NO_WAIT codify common timeouts. If a semTake() times out, it 
returns ERROR. Refer to the library of the semaphore type for the exact 
behavior of this operation. 


The semGive() call relinquishes a specified semaphore, unblocking a 
. pended task or making the semaphore available. Refer to the library of the 
semaphore type for the exact behavior of this operation. 


The semFlush() call may be used to atomically unblock all tasks pended on 
a semaphore queue, i.e., all tasks will be unblocked before any are allowed 
to run. It may be thought of as a broadcast operation in synchronization 
applications. The state of the semaphore is unchanged by the use of 
semFlush( ); it is not analogous to semGive( ). 


SEMAPHORE DELETION 

The semDelete( ) call terminates a semaphore and deallocates any associated 
memory. The deletion of a semaphore will unblock and return ERROR to all 
pended tasks. Care must be taken when deleting semaphores, particularly 
when used for mutual exclusion, to avoid pulling the rug out from under a 
task which has already taken the semaphore. Applications should adopt the 
protocol of only deleting semaphores that the deleting task has successfully 
taken. 


SEMAPHORE INFORMATION © 
The semInfo({ ) call is a useful debugging aid, reporting all tasks blockedona ..: - 
specified semaphore. It provides a snapshot of the queue at the time of the 
call, but because semaphores are dynamic, the information may be out-of... .:.+.4-- 
date by the time it is available. As with the current state of the. sane taaadas ope 
use of the queue of pended tasks:should be restricted. to debugging uses-: : : 
only. : 


INCLUDE FILE 
semLib.h 


SEE ALSO 
taskLib, semBLib, semCLib, ee ee Guide: Basic: QS ==3 2: 
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NAME 
semGive( ) - give a semaphore 


SYNOPSIS 
STATUS senGive (semId) 
SEM_ID semId; /* semaphore ID to give */ 


DESCRIPTION | 
This routine performs the give operation on a specified semaphore. 
Depending on the type of semaphore, the state of the semaphore and of the 
pending tasks may be affected. The behavior of semGive() is discussed 
fully in the library description of the semaphore type being used. 


RETURNS 
OK, or ERROR if the semaphore ID is invalid. 


SEE ALSO 
semLib, semBLib, semCLib, semMLib 
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NAME 
semTake( ) - take a semaphore 


SYNOPSIS | 
STATUS semTake (semId, timeout) 
SEM_ID semId; /* semaphore ID to take */ 
int timeout; /* timeout in ticks */ 


DESCRIPTION 
This routine performs the take operation on a specified semaphore. 
Depending on the type of semaphore, the state of the semaphore and the > 
calling task may be affected. The behavior of semTake( ) is discussed fully in 
the library description of the semaphore type being used. 


A timeout in ticks may be specified. If a task times out, semTake() will 
return ERROR. Timeouts of WAIT_FOREVER and NO_WAIT indicate to 
wait indefinitely or not to wait at all. 


semTake( ) is not callable from interrupt service routines. 
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RETURNS 
OK, or ERROR if the semaphore ID is invalid, or the task timed out. 


SEE ALSO 
semLib, semBLib, semCLib, semMLib 
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NAME 
semFlush() - unblock every task pended on a semaphore 
SYNOPSIS 


STATUS sew¥lush (semId) 
SEM ID semId; /* semaphore ID to unblock everyone for */ 


DESCRIPTION 
This routine atomically unblocks all tasks pended on a specified semaphore, 
i.e., all tasks will be unblocked before any is allowed to run. The state of the 
underlying semaphore is unchanged. All pended tasks will enter the ready 
queue before having a chance to execute. 


The flush operation is useful as a means of broadcast in synchronization 
applications. Its use is illegal for mutual-exclusion semaphores created with 
semMCreate( ). | 


RETURNS | | 
OK, or ERROR if the semaphore ID is invalid, or the operation is not sup- 


ported. 


SEE ALSO 
semLib, semBLib, semCLib, semMLib 


NAME 
semDelete() - delete a semaphore 


SYNOPSIS 
STATUS semPDelete (semId) 
SEX ID semId; /* semaphore ID to delete */ 
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DESCRIPTION 
This routine terminates and deallocates any memory associated with a 
specified semaphore. Any pended tasks will unblock and return ERROR. 


RETURNS 
OK, or ERROR if the semaphore ID is invalid. 


SEE ALSO 
semLib, semBLib, semCLib, semMLib 
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NAME 

semInfo( ) - get list of task IDs that are blocked on semaphore 
SYNOPSIS 

int semInfo (semId, idList, maxTasks) 


SEM ID semlId; /* semaphore ID to summarize */ 
int idList{}; /* array of task IDs to be filled in */ 
int maxTasks; /* max tasks idList can accommodate */ 


DESCRIPTION 
This routine reports the tasks that are blocked on a specified semaphore. Up 


to maxTasks task IDs are copied to the array specified by idList. The array is 
unordered. 

WARNING 
There is no guarantee. that all the tasks are still valid or that no new tasks 
have blocked by the time semInfo( ) returns. | 


RETURNS - 
The number of blocked: tasks:pladed-nsidlistxs ++: 


SEE ALSO 
semLib 
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_semMLib - mutual-exclusion semaphore library 


SYNOPSIS 
semMCreate( ) - create and initialize a mutual-exclusion semaphore 
semMGiveForce( ) - give a mutual-exclusion semaphore without restrictions 


SEX ID seatiCreate (options) 
STATUS senMGiveForce (semId) 


DESCRIPTION 
This library provides the interface to Vx960 mutual-exclusion semaphores. 
Mutual-exclusion semaphores offer convenient options suited for situations 
requiring mutually exclusive access to resources. Typical applications 
include sharing devices and protecting data structures. Mutual-exclusion 
semaphores are used by many higher-level Vx960 facilities. 


The mutual-exclusion semaphore is a specialized version of the. binary 
semaphore designed to address issues inherent in mutual exclusion, such as 
recursive access to resources, priority inversion, and deletion safety. The 
fundamental behavior of the mutual-exclusion semaphore is identical to the 
binary semaphore (see the manual entry for semBLib), except for the follow- 
ing restrictions: 


- It can only be used for mutual exclusion. 

- It can only be given by the task that took it. 

- It may not be taken or given from interrupt level. 
- The semFlush() operation is illegal. 


These last two operations have no:meaning in mutual-exclusion situations... ::: «+: 


RECURSIVE RESOURCE ACCESS. Raccunsi¥e:gEs0UR< 3 +. 
A special feature of the mutual-exclusion s oniapnores is that-it may be taken-: 
“recursively,” i.e., it can be takénemore-than once by the task that: owns: it: oO: 
before finally being released. Recursion: is- useful for a set of routines. that: 
need mutually exclusive access. to a resource, but may need to call each 
other. 


Recursion is made possible by the fact that the system keeps track of which 
task currently owns a mutual-exclusion semaphore. Before being released, a 
mutual-exclusion semaphore taken recursively must be given the same 
number of times it has been taken; this is tracked by means of a count which 
is incremented with each semTake( ) and decremented with each semGive( ). 


The example below illustrates recursive use of a mutual-exclusion 
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semaphore. Function A requires access to a resource which it acquires by 
taking semM; function A may also need to call function B, which also 
requires semM: 


SEM_ID sexs; 
seu = semlCreate (...); 


funcaA () 
{ 
semfake (sem, WAIT FOREVER) ; 
funcB ()} 
 semGive (sent) ; 
} 


funcB () 


{ 
semTake (sem, WAIT FOREVER) ; 


semGive (sem); 
} 


PRIORITY-INVERSION SAFETY 
If the option SEM_INVERSION SAFE is selected, the library adopts a 
priority-inheritance protocol to resolve potential occurrences of “priority 
inversion,’ a problem stemming from the use semaphores for mutual exclu- 
sion. Priority inversion arises when a higher-priority task is forced to wait 
an indefinite period of time for the completion of a lower-priority task. 


Consider the following scenario: T1, T2, and T3 are tasks of high, medium, 
and low priority, respectively. T3 has acquired some resource by taking its 
associated semaphore. When T1 preempts T3 and contends for the resource 
by taking the same semaphore, it becomes blocked. If we could be assured 
that T1 would be blocked no longer than the time it normally takes T3 to fin- 
_ ish with the resource, the situation would not be problematic. However, the 
low-priority task is vulnerable to preemption by medium-priority tasks; a 
preempting task, T2, could inhibit T3 from relinquishing the resource. This 
condition could persist, blocking T1 for an indefinite period of time. 


The priority-inheritance protocol solves the problem of priority inversion by 
elevating the priority of T3 to the priority of T1 during the time T1 is blocked 
on T3. This protects T3, and indirectly T1, from preemption by T2. Stated 
more generally, the priority-inheritance protocol assures that a task which 
owns a resource will execute at the priority of the highest priority task 
blocked on that resource. When execution is complete, the task gives up the 
resource and returns to its normal, or standard, priority. Hence, the 
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‘inheriting’ task is protected from preemption by any intermediate-priority 
tasks. 


The priority-inheritance protocol also takes into consideration a task’s own- 
ership of more than one mutual-exclusion semaphore at a time. Such a task 
will execute at the priority of the highest priority task blocked on any of its 
owned resources. The task will return to its normal priority only after relin- 
quishing all of its mutual-exclusion semaphores that have the inversion- 
safety option enabled. 


TASK-DELETION SAFETY 
If the option SEM_DELETE_SAFE is selected, the task owning the sema- 
phore will be protected from deletion as long as it owns the semaphore. 
This solves another problem endemic to mutual exclusion. Deleting a task 
executing in a critical region can be catastrophic. The resource could be left 
in a corrupted state and the semaphore guarding the resource would be una- 
vailable, effectively shutting off all access to the resource. 


As discussed in taskLib, the primitives taskSafe() and taskUnsafe() offer 
one solution, but as this type of protection goes hand in hand with mutual 
exclusion, the mutual-exclusion semaphore provides the option 
SEM_DELETE SAFE, which enables an implicit taskSafe() with each 
semTake(), and a taskUnsafe() with each semGive(). This convenience is 
also more efficient, as the resulting code requires fewer entrances to the ker- 
nel. 


CAVEATS 

There is no mechanism to give back or reclaim semaphores automatically 
when tasks are suspended or deleted. Such a mechanism, though desirable, 
is not currently feasible. Without explicit knowledge of the state of the 
guarded resource or region, reckless automatic reclamation of a semaphore 
could leave the resource in a partial state. Thus if a task ceases execution 
unexpectedly, as with a bus error, currently owned semaphores will not be 
given back, effectively leaving a resource permanently unavailable. The 
SEM_DELETE_ SAFE option partially protects an application, to the extent 
that unexpected deletions will be deferred until the resource is released. 


SEE ALSO | 
semLib, semBLib, semCLib, Programmer's Guide: Basic OS 
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NAME 
semMCreate( ) - create and initialize a mutual-exclusion semaphore 


SYNOPSIS 
SEM_ID sexiCreate (options) | 
int options; /* mitex semaphore options */ 
DESCRIPTION 
This routine allocates and initializes a mutual-exclusion semaphore. The 
semaphore state is initialized to full. 


Semaphore options include the following: 


SEM_Q_ PRIORITY 
- Queue pended tasks on the basis of their priority. 


SEM_Q_ FIFO 
- Queue pended tasks on a first-in-first-out basis. 


SEM_DELETE_ SAFE 
- Protect a task that owns the semaphore from unexpected dele- 
tion. This option enables an implicit taskSafe() for each 
semTake( ), and an implicit taskUnsafe() for each semGive( ). 


SEM_INVERSION_SAFE 
- Protect the system from priority inversion. With this option, the 
task owning the semaphore will execute at the highest priority of 
the tasks pended on the semaphore if it is higher than its current 
priority. This option must be accompanied by the 
SEM_Q_ PRIORITY queuing mode. : 


RETURNS 
The semaphore ID, or NULL if memory cannot be allocated. 


SEE ALSO 
semMLib, semLib, semBLib, taskSafe( ), taskUnsafe( ) 
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NAME | 
semMGiveForce( ) - give a mutual-exclusion semaphore without restrictions 


SYNOPSIS | 
STATUS seutGiverorce (semId) 
SEX_ID semId; /* semaphore ID to give */ 


DESCRIPTION | 
This routine gives a mutual-exclusion semaphore not owned by the calling 


task. It is intended as a debugging aid only. 


The routine is particularly useful when a task dies while holding some 
mutual-exclusion semaphore, because the semaphore can be resurrected. 
The routine will give the semaphore to the next task in the pend queue or 
make the semaphore full if no tasks are pending. In effect, execution will 
continue as if the task owning the semaphore had actually given the sema- 
phore. 


CAVEATS 
This routine should only be used as a debugging aid, when the condition of 
the semaphore is known. It can only be called ey a task that does not own 
the semaphore. 


RETURNS 
OK, or ERROR if the semaphore ID is invalid, or the routine is called by the 


task owning the semaphore. 


SEE ALSO 
semM Lib, semGive( ) 
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NAME 
semOLib - version 4.x binary semaphore library 


SYNOPSIS 
semCreate() - create and initialize a version 4.x binary semaphore 
semInit( ) - initialize a static binary semaphore 
semClear( ) - take a version 4.x semaphore if the semaphore is available 


SEM_ID semCreate () 
STATUS semInit (pSemaphore) 
STATUS semClear (semId) 


DESCRIPTION 
This library is provided for _— compatibility with Vx960 version 4.x 
semaphores. The semaphores are identical to 5.0 binary semaphores except 
that timeouts — missing or specified — are ignored. 


For backward compatibility, semCreate() operates as before, allocating and 
initializing a 4.x-style semaphore. Likewise, semClear() has been imple- 
mented as a semTake( ) with a timeout of NO_WAIT. 


A fuller discussion of the behavior of binary semaphores may be found in 
semBLib. 


SEE ALSO 
semLib, semBLib, Programmer's Guide: Basic OS 


NAME 
semCreate( ) - create and initialize a version 4.x binary semaphore 


SYNOPSIS 
SEM ID sesCreate () 


DESCRIPTION 
This routine allocates a version 4.x binary semaphore. The semaphore is ini- 
tialized to empty. After initialization, it must be given before it can be taken. 


RETURNS 
The semaphore ID, or NULL if memory cannot be allocated. 
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SEE ALSO 
semOLib, semInit( ) 
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NAME 
semInit() - initialize a static binary semaphore 


SYNOPSIS 
STATUS semInit (pSemaphore) 
SEMAPHORE ‘*pSemaphore; /* 4.x semaphore to initialize */ 


DESCRIPTION 
In some instances, a semaphore cannot be created with semCreate() but is a 
static object. This routine will initialize static version 4.x semaphores. 


RETURNS 
OK, or ERROR if the semaphore cannot be initialized. 


SEE ALSO 
semOLib, semCreate( ) 


NAME 


semClear() - take a version 4.x semaphore if the semaphore is available 


SYNOPSIS 
STATUS semClear (senId) 


SEM ID semId; /* semaphore ID to empty */ 


DESCRIPTION : 
This routine takes a semaphore if it is available (full), otherwise no action is 
taken except to return ERROR. This routine never preempts the caller. 


RETURNS 
OK, or ERROR if the semaphore is unavailable. 


SEE ALSO 
semOLib 
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NAME | 
shellLib - shell execution routines 


SYNOPSIS 
shellInit() - start the shell 
shell( ) - the shell entry point 
sheliScriptAbort{ ) - signal shell to stop processing a script 
shellHistory( ) - display (or set) shell history 
shellPromptSet( ) - change the shell prompt 
shellOrigStdSet{ ) - set the shell’s default input/output /error fds 
shellLock( ) - lock access to shell 


STATUS shelliInit (stackSize, arg) 
- VOID shell (interactive) 

VOID shellScriptAbort () 

VOID shellmwistory (size) 

VOID shellPromptSet (newPrompt ) 

VOID shellorigStdSet (which, fd) 

ROGz%, shellLock (request) 


DESCRIPTION 
This module contains the execution support routines for the Vx960 shell. It 
provides the basic programmer's interface to Vx960. It is a C-expression 
interpreter, containing no built-in commands. 


The nature, use, and syntax of the shell is more fully described in the “Shell” 
chapter of the Vx960 Programmer's Guide. 


SEE ALSO 
ledLib, Programmer's Guide: Shell 
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NAME 
shellInit() - start the shell 


SYNOPSIS 
STATUS shellinit (stackSize, arg) 
int stackSize; /* shell stack (0 = previous/default value) */ 
imt arg; /* argument to shell task */ 
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DESCRIPTION 
This routine starts the aie task. If INCLUDE_SHELL is defined in 
configAILh, this is done by the root task, usrRoot{ ), in usrConfig.c. 


RETURNS 
OK, or ERROR. 


SEE ALSO 
shellLib 


NAME 
shell( ) - the shell entry point 


SYNOPSIS 
VOID shell (interactive) 
| BOOL, interactive; /* should be TRUE, except for a script */ 


DESCRIPTION 
This routine is the shell task. It is started with a single parameter that indi- 
cates whether this is an interactive:shell to be used from a terminal or a 
socket, or a shell that executes a script. : 


Normally, the shell is spawned in interactive mode by the root task, 
usrRoot{ ), when Vx960 starts upAfter that, shell (: eamans only to execute 
scripts, or when the shell is restarted: after ar abort. - 


The shell gets its input from standard.input.and. sends output to standard 
output. Both standard input and:standardioutputJare! initially: assigned : to 


the console, but are redirected byitelnetdTaskt) and rlogindTask(cizata i 2c38:) avid. 


The shell is not reentrant, since yaec: doés-not:generate::a reentrant i ee 
Therefore, there can be only a single:sheltexécuting:at.one:time:: ve 


RETURNS 
N/A 


SEE ALSO 
shellLib 
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NAME 
shellScriptAbort( ) - signal shell to stop processing a script 


SYNOPSIS 
VOID shellScriptAbort () 


DESCRIPTION 
This routine signals the shell to abort processing a script file. It can be called 
from within a script if an error is detected. 


RETURNS 
N/A 


SEE ALSO 
shellLib 


NAME 
shellHistory( ) - display (or set) shell history 


SYNOPSIS 
VOID shellHistory (size) 
int size; /* 0 = display, >0 = set history to new size */ 


DESCRIPTION 
This routine displays shell history, or resets the default number of com- 
mands displayed by shell history to size. By default, history size is 20 com- 
mands. Shell history is actually maintained by ledLib. 


RETURNS 
N/A 


SEE ALSO 
shellLib, ledLib, h() 
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NAME 
shellPromptSet( ) - change the shell prompt 


SYNOPSIS 
VOID shellPromptSet (newProspt) 
char ‘*newPrompt; /* string to become new shell proaspt */ 


DESCRIPTION 
This routine changes the shell prompt string to newPrompt. 


RETURNS 
N/A 


SEE ALSO 
-shellLib 


NAME 


shellOrigStdSet( ) - set the shell’s default input/output /error fds 


SYNOPSIS 
VOID shellorigstdset (which, fd) 
int which; /* STD_IM, STD_OUT, STD_ERR */ 
int fd; /* fd to be default */ 


DESCRIPTION 
This routine is called to change the shell’s default standard input/output / 
error fd. Normally, it is used only by the shell, rlogindTask(), and 
telnetdTask{ ). Values for which can be STD_IN, STD_OUT, or STD_ERR as 
defined in vxWorks.h. Any fd for a file or device can be used for fad. 


RETURNS 
N/A 


SEE ALSO 
shellLib 
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NAME _ 
shellLock( ) - lock access to shell 


SYNOPSIS 
BOOK, shellLock (request) | 
BOOL request; /* TRUE = lock, FALSE = unlock */ 


DESCRIPTION 
This routine locks or unlocks access to the shell. When locked, cooperating 
tasks, such as telnetdTask( ) and rlogindTask( ), will not take the shell. 


RET URNS 
When request is “lock’’, the return will be TRUE if the call locks the shell, or 
FALSE if the call fails. When request is “unlock”, the return will be TRUE if 
the call unlocks the shell, or FALSE if the call fails. 


SEE ALSO 
shellLib 
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NAME 


sigLib - software signal facility library 


SYNOPSIS 
sigInit( ) - initialize the signal facilities 
sigvec( ) - install a signal handler 
sigstack( ) - install a separate signal stack 
sigsetmask() - set the signal mask 
sigblock( ) - add to set of blocked signals 
pause() - sleep until the occurrence of a signal 
kill() - send a signal to a task 
sigRaise( ) - send a signal to a task 


STATUS sigInit () 

STATUS sigvec (sig, pVec, pOvec) 
STATUS sigstack (pSs, pOss) 

int sigsetmask (mask) 

int sigblock (mask) 

STATUS pause () 

STATUS kill (tid, signal) 

STATUS sigRaise (tid, signal, code) 


DESCRIPTION | 

This library provides a UNIX BSD. 4.3-compatible. software signal facility. 
Signals are used to alter the flow:contreleof:tasks;sby.:communicating:asyn- «=: 
chronous events within or betweentaskcentexts:vAny: task:or-interrupt ser-. «+=, 
vice can “raise” (or send) a signal-to-a partictilar-task:--The task: being sig-" 
naled will immediately suspen drits<rirreit thread of bxecution-aid invoke a: 

_ task-specified “signal handler?czoutine::i:cthe signal thandler’ iscaiiuser-:: = - | 

_ supplied routine that is bound top pécific signal -and performs: Whatexer's errant 
actions are necessary whenevercithe:signal:is:azeceived:. Signals ‘are most. 
appropriate for error and exception baridlinjprrather ee eee ere pire oars 
pose intertask communication nyechanism: =: <2: 


In many ways, signals. are analogous: tovhardware.interrupts.:.The signal . 
facility provides a set of 31 distinct:signals:--A:signal:can.be-raised by calling 
kill() or sigRaise(), which is analogous toan:interrupt ‘or hardware excep- 
tion. A signal handler is bound:to a particular signal with sigvec() in much 
the same way that an interrupt service routine is connected to an interrupt 
vector with intConnect(). Signals are blocked for the duration of the signal 
handler, just as interrupts are locked out for the duration of the interrupt 
service routine. 
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Tasks can block the occurrence of certain signals with sigblock() and 
sigsetrnask(), just as the interrupt level can be raised or lowered to block 
out levels of interrupts. If a signal is blocked when it is raised, its handler 


routine will be called when the signal becomes unblocked. 
Signal handlers are passed several parameters and should be defined as: 


VOID sigNandler (sig, code, sigContext) 
int sig; /* signal number * 
int code; /* additional code * 
SIGCONTEXT *sigContext; /* context of task before signal * 
{ 


} 


The parameter code distinguishes signal variants. For example, both numeric 
overflow and zero divide raise SIGFPE (floating-point exception) but have 
different values for code. 


EXCEPTION PROCESSING 


Certain signals (defined below) are raised automatically when hardware 
exceptions are encountered. This mechanism allows user-defined exception 
handlers to be installed. This is useful for recovering from catastrophic 
events such as bus or arithmetic errors. Typically, setjmp() is called to 
define the point in the program where control will be restored, and 
longjmp() is called in the signal handler to restore that context. Note that 
longjmp( ) restores the state of the task’s signal mask and its onstack flag. If 
a user-defined handler is not installed for the given signal, the default action 


_ is to loga message to the console and suspend the task. 
_ Of the 31 signals defined by UNIX BSD 4.3, only a few are meaningful in the 


1-344 


Vx960 environment. The following can be raised by Vx960: 


i960 version: 


Signal Code | Exception 
SIGSUS BUS_BUSERR ; address error or parity error (MMI) 
SIGEUS WULL sigsegvy (NMI) 
SIGILL ILL INVALID OPCODE invalid opcode 
SIGILL ILL_UNIMPLEMENTED unimplemented instruction 
SIGILL BUS ALIGN | unaligned instruction (80960CA only) 
SIGILL ILL_INVALID_OPERAMD invalid instruction operand 
SIGILL ILL _PRIVVIO_FAULT constraint privileged instruction 
SIGILL ILL_CONSTR_RANGE_FAULT constraint range fault 

 SIGILL ILL_PROT_LENGIZ protection length fault 
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SIGILL ILL TYPE MISMATCH 


SIGTRAP FST_IMSTRUCTION TRACE 
SIGTRAP FST_BRAMCH TRACE 
SIQTRAP FST_CALL TRACE 
SIGTRAP FST_RETURN TRACE 
SIGIRAP FST_PRERETURM TRACE 
SIGTRAP FST_SUPERVISOR_TRACE 
SIQTRAP FST_BREAKPOINT TRACE 


SIGFPE FPE_INTDIV TRAP 
SIGFPE FPE_IWTOVF_TRAP 


80960SB /80960KB only: 
Signal Code 


SIGFPE ¥FPE_FLTOVF_TRAP 
SIGFPE ¥PE_FLSUND TRAP 
SIGFPK ¥FPE_FLTINV TRAP 
SIGFPE FPE_FLTDIV_TRAP 
SIGFPE ¥FPE_FLTINEX_TRAP 
SIGFPE FPE_FLTOPERR_TRAP 
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type mismatch fault 


instruction trace 
branch trace 
call trace 
return trace 
prereturn trace 
supervisor trace 


breakpoint trace 


zero divide 
integer overflow 


Exception 


floating overflow 
floating underflow 
floating invalid operation 
floating zero divide 
floating inexact 


floating reserved encoding 


Other signals can be used by a Vx960 application. 


CAVEATS | 
If a signal is directed at a task that is pended, the signal handler will not be 
invoked until the task becomes runnable. 


INCLUDE FILE 
sigLib.h 


SEE ALSO 
intLib, UNIX BSD 4.3 documentation 


NAME 
sigInit( ) - initialize the signal facilities 


SYNOPSIS 
STATUS sigInit () 
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DESCRIPTION | 
This routine initializes the signal facilities. It is usually called from the sys- 
tom start-up routine usrinit{ \ lin usrConfig, be fore interrupts are enabled. 
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RETURNS 
OK, or ERROR if the create /delete hooks could not be installed. 


SEE ALSO 
sigLib 


NAME 
sigvec( ) - install a signal handler 


SYNOPSIS 


STATUS sigvec (sig, pVec, pOvec) 
int sig; /* signal to which tha handler will be attached */ 


SIGVEC ‘*pVec; /* handler information if I= MULL */ 
SIGVEC ‘*pOvec; /* previous handler info is copyed here if != WULL */ 


DESCRIPTION 
This routine binds a signal handler routine referenced by pVec to a specified 
signal sig. It can also be used ‘to determine which handler, if any, has been 
bound to a particular signal: sigvec( ) will copy current signal handler infor- 
mation for sig to pOvec- and-install no:signal handler if pVec is set to null (0). 


Both pVec and pOvec are pointers to a structure of type SIGVEC. The infor- 
mation passed includes not-only: the signal: handler routine, but.also the sig- 
nal mask and ee cnes rau cea SIGVEC-and the.available options are 
defined in sigLib.ieevire: 2.2 : 


RETURNS 
OK, or ERROR if the Se signal number is invalid. 


SEE ALSO 
sigLib 
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NAME 
sigstack( ) - install a separate signal stack 


SYNOPSIS 
STATUS sigstack (pés, pOss) 
SIGSTACK ‘*pSs; /* new signal stack info if i= MULL */ 
SIGSTACK *pOss; /* copy old signal stack info here if j= MULL */ 


DESCRIPTION | 
This routine specifies an alternate stack, to be used for the duration of signal 
handling. When a signal handler is installed with siguec( ), the sv_flags ele- 
ment of the SIGVEC structure must have the SV ONSTACK bit turned on 
for the signal stack to be switched in. | 


RETURNS | 
OK (always). 


SEE ALSO 
sigLib 


NAME 


sigsetmask( ) - set the signal mask~?..-7¢2~1: 202 ; 
SYNOPSIS 
int sigsetmask (mask) fe PP! 2, i : 
int mask; /* new signal mask “/5 senses #2 ercr | 
DESCRIPTION | 3 
This routine sets the calling task’s: signal mask-te the givenwvalue; A-one (A).:5 5. 23:+ 
in the bit mask indicates that the:given-signakis:blocked: from ‘delivery: ‘Use=: 25 =:.- 
the macro SIGMASK to construct the-mask-for a:giver signal number. '::::5 5° fers 


RETURNS 
The previous value of the signal miask. ---" 


SEE ALSO 
sigLib, sigblock( ) 


Rev: 30 Aug 91 Intel 1 - 347 


Vx960 5.0 - Reference Manual 


— Ue S: 
EOS 
a 
S 


eS airs Re 
SOSA RAEN a SO 
— RE 


NAME 
sigblock( ) - add to set of blocked signals 


SYNOPSIS 
int sigblock (mask) 
int mask; /* mask of additional signals to be blocked */ 


DESCRIPTION 
This routine adds the signals in mask to the task’s set of blocked signals. A 
one (1) in the bit mask indicates that the given signal is blocked from 
delivery. Use the macro SIGMASK to construct the mask for a given signal 
number. 


RETURNS | 
The previous value of the signal mask. 


SEE ALSO 
sigLib, sigsetmask( ) 


NAME 


pause()- sleep until the occurrence of a signal 


SYNOPSIS 
STATUS pause () 


DESCRIPTION 
This routine blocks task execution until the occurrence of a signal. After the 
signal handler has executed, pause( ) returns. 


RETURNS 
ERROR (always). 


SEE ALSO 
sigLib 
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NAME 
kill( ) - send a signal to a task 


SYNOPSIS 
STATUS kill (tid, signal) 
int tid; /* task to which the signal is directed */ 
int signal; /* the signal to send the task */ 


DESCRIPTION 
This routine sends a signal to the specified task. The task must have previ- 
ously installed a signal handler with sigvec( ). 


CAVEAT 
If the task is pended, the signal will not be delivered until the task is ready 
to run. 


RETURNS 
OK, or ERROR if the task is not found, the task has no signal handler for sig- 
nal, or the signal cannot be delivered. 


SEE ALSO 
sigLib, siguvec( ), sigRaise( ) 


NAME 
sigRaise() - send a signal to a task 


SYNOPSIS 
STATUS sigRaise (tid, signal, code) 
int tid; /* task to which the signal is directed */ 
int signal; /* the signal to send the task */ 
int code; /* additional code */ 


DESCRIPTION 
This routine sends a signal to the specified task. It provides the same 
mechanism as kill(), but allows an additional code identifying signal vari- 
ants to be passed to the signal handler. 


RETURNS 
OK, or ERROR if the task is not found, the task has no signal handler for sig- 
nal, or the signal cannot be delivered. | 
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SEE ALSO 
sigLib, sigvec( ), kill() 
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NAME 
sockLib - UNIX BSD 4.3 compatible socket library 
SYNOPSIS 


socket() - open a socket 

bind( ) - bind a name to a socket 

listen() - enable connections to a socket 
accept() - accept a connection from a socket 
connect( ) - initiate a connection to a socket 
sendto( ) - send a message to a socket 

send() - send data to a socket 

sendmsg() - send a message to a socket 
recufrom() - receive a message from a socket 
recv( ) - receive data from a socket . 

recumsg() - receive a message from a socket 
setsockopt() - set socket options 

getsockopt( ) - get socket options 
getsockname() - get a socket name 
getpeername( ) - get the name of a connected peer 
shutdown( ) - shut down a network connection 


int socket (domain, type, protocol) 

STATUS bind (s, name, nanmelen) 

STATUS listen (s, backlog) 

int accept (s, addr, addrlen) 

STATUS connect (s, name, namelen) 

int sendto (s, buf, buflLen, flags, to, tolen) 

int send (s, buf, buflen, flags) 

int sendasg (sd, mp, flags) Bias ee ies 

int recvfrom (s, buf, bufLen, flags, fa. pironten) 
int recv (s, buf, buflen, flags) 

int recvmsg (sd, mp, flags) 
STATUS setsockopt (s, level, optname, optval, optlen) 
STATUS getsockopt (s, level, optname, optval, optien) 
STATUS getsockname (s, name, namelen) | ; 
STATUS getpeername (s, name, namelen) 

STATUS shutdown (s, how) 


DESCRIPTION 
This library provides UNIX BSD 4.3 compatible socket calls. These calls may 
be used to open, close, read, and write sockets, either on the same CPU or 
over a network. The calling sequences of these routines are identical to 
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INCLUDE FILES | 
types.h, mbuf.h, socket.h, socketvar.h 


SEE ALSO 
UNIX BSD 4.3 documentation, netLib Programmer's Guide: Network 
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NAME 
socket( ) - open a socket 


SYNOPSIS 
int socket (domain, type, protocol) 
int domain; /* address family (e.g., AF_INET) */ 


int type; /* pocket type (e.g., SOCK_STREAM) */ 
int pretocel; /* socket protocel (usually 0) */ 
DESCRIPTION | 


This routine opens a socket and returns a socket descriptor. The socket 
descriptor is passed to the other socket routines to identify the socket. The 
socket descriptor is a standard I/O system “file descriptor’ (fd) and can be 
used with the close( ), read( ), write( ), and ioctl( ) routines. 


RETURNS 
A socket descriptor, or ERROR. 


SEE ALSO 
sockLib 


NAME 


bind() - bind a name to a socket 


SYNOPSIS 
STATUS bind (s, name, namelen) 
int s} /* socket descriptor */ 
struct sockaddr ‘name; /* name to be bound */ 
int namelen; /* length of name */ 
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DESCRIPTION 
This routine associates a network address (also referred to as its “‘name’) 
with a given socket so that other processes can connect or send to it. When 
a socket is created with socket( ), it belongs to an address family but has no 
assigned name. 


RETURNS 
OK, or ERROR if there is an invalid socket, the address is either unavailable 
or in use, or the socket is already bound. 


SEE ALSO 
sockLib 


NAME 
listen() - enable connections to a socket 
SYNOPSIS 
STATUS listen (s, backlog) 
int s; /* gocket descriptor */ 
int backlog; /* number of connections to queue */ 
DESCRIPTION 
This routine enables connections to a socket. It also specifies the maximum 
number of unaccepted connections that can be pending at one time (backlog). 
After enabling connections with listen(), connections are actually accepted 
by accept( ). 
RETURNS 
OK, or ERROR if the socket is invalid or unable to listen. 
SEE ALSO 
sockLib 
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NAME 
accept() - accept a connection from a socket 
SYNOPSIS 
int accept (s, addr, addrilen) 
int 8; /* socket. descriptor */ 
struct sockaddr ‘addr; /* peer address */ 
int taddrlien; /* peer address length */ 
DESCRIPTION 


This routine accepts a connection on a socket, and returns a new socket 
created for the connection. The socket must be bound to an address with 
bind( ), and enabled for connections by a call to listen(). The accept() rou- 
tine dequeues the first connection and creates a new socket with the same 
properties as s. It blocks the caller until a connection is present, unless the 
socket is marked as non-blocking. 


RETURNS 
A socket descriptor, or ERROR if the call fails. 


SEE ALSO 
sockLib 


NAME 
connect( ) - initiate a connection to a socket 
SYNOPSIS 
STATUS connect (s, name, namelen) 
int 8} /* socket descriptor */ 
struct sockaddr ‘“name; ecsenieabbacheurebaberameta 
int namelen; /* length of name, in bytes * 
DESCRIPTION 


If s is a socket of type SOCK STREAM, this routine establishes a virtual cir- 
cuit between s and another socket specified by name. If s is of the type 
SOCK DGRAM, it permanently specifies the peer to which messages are 
sent. The name specifies the address of the other socket. 
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RETURNS 
OK if the connection is successful, or ERROR if the call fails. 


SEE ALSO 
sockLib 
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NAME 
| sendto( ) - send a message to a socket 
SYNOPSIS 
int sendto (s, buf, buflen, flags, to, tolen) 
int s; /* socket on which to send data «/ 
caddr t buf ; /* pointer to data buffer */ 
int bufLen; /* length of buffer */ 
int flags; /* flags to underlying protocols */ 
struct sockaddr *to; /* vecipient’s address */ 
int tolen; /* length of to sockaddr */ 
DESCRIPTION 
This routine sends a message to the datagram socket named by to. The 
socket s will be received by the receiver as the sending socket. 
RETURNS 
The number of bytes sent, or ERROR if the call fails. 
SEE ALSO 
sockLib 
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NAME 
send{ ) - send data to a socket 
SYNOPSIS 
int send (s, buf, bufLen, flags) 
int s; /* socket on which to send */ 
char ‘buf; /* pointer to buffer to transmit */ 
int bufLen; /* length of buffer */ . 
int flags; /* flags to underlying protocols */ 
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DESCRIPTION 
This routine transmits data on a previously established connection-based 


socket. 


RETURNS | 
The number of bytes sent, or ERROR if the call fails. 


SEE ALSO 
sockLib 


NAME 
sendmsg() - send a message to a socket 
SYNOPSIS 
int sendmseg (sd, mp, flags) 
int | sd; /* socket on which to transmit */ 
struct msghdr ‘mp; /* scatter-gather message header */ 
int flags; /* flags to underlying protocols */ 
DESCRIPTION 


This routine sends a message to a socket. It may be used in place of 
sendto() to decrease the overhead of reconstructing the message-header 
structure (msghdr) for each message. 


RETURNS 
The number of bytes sent, or ERROR if the call fails. 


SEE ALSO 
sockLib 
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NAME 
recufrom|( ) - receive a message from a socket 
SYNOPSIS 
int recvfrom (s, buf, bufLen, flags, from, p¥FromLen) 
| int Bs} _f* socket on which to receive data */ 
char - *buf; /* pointer to data buffer */ 
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dint bufLen; /* length of buffer */ 

int flags; /* flags to underlying protocols */ 

struct sockaddr *from; /* gete filled in with sender’s address */ 

int *“pFromLen; /* value/result length of ‘from’ */ 
DESCRIPTION 


This routine receives data from a socket regardless of whether it is con- 
nected. If from is non-zero, the address of the sender's socket is copied to it. 

_ The value-result parameter pFromLen should be initialized to the size of the 
from buffer. On return, pFromLen contains the actual size of the address 
stored in from. 


RETURNS 
The number of number of bytes received, or ERROR if the call fails. 


SEE ALSO 
sockLib 


NAME 


recu( ) - receive data from a socket 


SYNOPSIS 
int recv (s, buf, buflen, flags) | 
int 383 /* gockat on which to receive data */ 
char *buf; /* pointer to buffer where data will be written */ 
int bufLen; /* length of buffer */ 
int flags; /* flags to underlying protocols */ 


DESCRIPTION 
This routine receives data from a connected socket. 


RETURNS . 
The number of bytes received, or ERROR if the call fails. 


SEE ALSO 
sockLib 
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NAME 
recumsg( ) - receive a message from a socket 


SYNOPSIS 
int recvmsg (sd, mp, flags) 
int | ad; /* socket on which to receive */ 
struct meghdr ‘mp; /* scatter-gather message header */ 
int flags; /* flags to underlying protocols */ 


DESCRIPTION | 
This routine receives message on a socket. It may be used in place of 
recufrom() to decrease the overhead of breaking down the message-header 
structure (msghdr) for each message. 


RETURNS | 
The number of bytes received, or ERROR if the call fails. 


SEE ALSO 
sockLib 


NAME 


setsockopt() - set socket options 


SYNOPSIS 
STATUS setsockopt (s, level, optname, cptval, optlen) 
int ss; /*. target socket */ 
int level; /* protocol level at which geen. resides */ 
int optname; /* option name */ 
char ‘*optval; /* pointer to option value */ 
int optlen; /* option length * 
DESCRIPTION 
This routine sets the options associated with a socket. To manipulate 


options at the “socket” level, level should be SOL_SOCKET. Any other lev- 
els should use the appropriate protocol number. 


RETURNS 
OK, or ERROR if there is an invalid socket, an unknown option, an option 
length greater than MLEN, insufficient mbufs, or the routine is unable to set 
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the specified option. 


SEE ALSO 
sockLib 


NAME 
getsockopt( ) - get socket options 


SYNOPSIS 
STATUS getsockopt (s, level, optname, optval, optlen) 
int 8} /* socket */ 
int level; /* protocol level for the options */ 
int optname; /* name of the option */ | . 
char ‘*optval; /* where option is to be returned */ 
int ‘*optlen; /* where option length is to be returned */ 


DESCRIPTION : 
This routine returns relevant option values associated with a socket. T 
manipulate options at the “socket” level, level should be SOL_SOCKET. 
Any other levels should use the appropriate protocol number. 


RETURNS 
OK, or ERROR if there is an invalid socket, an unknown option, or the rou- 
tine is unable to get the specified option. 


SEE ALSO 
sockLib 
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NAME 
getsockname() - get a socket name 


SYNOPSIS 
STATUS getsockname (s, name, namelen) 
int Bs} /* socket descriptor */ 
struct sockaddr ‘name; /* where to return name */ 
int *namelen; /* amount of space available in name, */ 
/* later filled in with actual size of neme */ 
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DESCRIPTION 
This routine gets the current name for the Spence socket s. The parameter 
namelen should be initialized to indicate the amount of space referenced by 
name. On return, the name of the socket is copied to name and the actual size 
of the socket name is copied to namelen. 


RETURNS 
OK, or ERROR if the socket is invalid « or not connected. 


SEE ALSO 
sockLib 


NAME 


getpeername() - get the name of a connected peer 


SYNOPSIS 
STATUS getpeername (s, name, nameler) 
int Ss} /* socket descriptor * 
struct sockaddr ‘*name; /* where to return name */ 
int tnamelen; /* amount of space available in name, */ 
/* later filled in with actual size of name */ 


DESCRIPTION 
This routine gets the name of the peer connected to socket s. The parameter 
namelen should be initialized to indicate the amount of space referenced by 
name. On return, the name of the socket is copied to name and the actual size 
of the socket name is copied to namelen. 


RETURNS 
OK, or ERROR if the socket is invalid or not connected. 


SEE ALSO 
sockLib 
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NAME 
shutdown( ) - shut down a network connection 


SYNOPSIS 
STATUS shutdown (s, how) 
int s; /* the socket to shutdown */ 
int how; /* 0 = receives disallowed */ 
/* 1 = sends disallowed */ 
/* 2 = sends and receives disallowed */ 


- DESCRIPTION 

This routine shuts down all, or part, of a connection-based socket s. If the 
value of how is 0, receives will be disallowed. If how is 1, sends will be disal- 
lowed. If how is 2, both sends and receives are disallowed. 


RETURNS 
OK, or ERROR if the socket is invalid or not connected. 


SEE ALSO 
sockLib 
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NAME 
spyLib - spy CPU activity library 


SYNOPSIS 


spyClkStart( ) - start collecting task activity data 
spyClkStop( ) - stop collecting task activity data 
spyReport( ) - display task activity data 
spyTask( ) - run periodic task activity reports 
spyStop( ) - stop spying and reporting 
spy() - begin periodic task activity reports 

_ spyHelp( ) - display task monitoring help menu 


STATUS spyClkStart (intsPerSec) 
VOID spyClkStop () 

VOID spyReport () 

VOID spyTask (freq) 

VOID spy8top () 

VOID spy (freq, ticksPerSec) 


VOID spyelp () 


DESCRIPTION 
This library provides a facility to monitor tasks’ use of the CPU. The pri- 
mary interface routine, spy(), periodically calls spyReport() to display the 
amount of CPU time utilized by each task, the amount of time spent at inter- 
rupt level, the amount ‘of time spent in the kernel, and the amount of idle 
time. It also displays .the-total usage since the start of spy() (or the last call 
to spyClkStart{ )), and the change in usage since the last spyReport{ ). 


CPU usage can alsa be: monitored manually. by calling spyClkStart() and 


spyReport( ) insteadipfspy(’). + In thisease; spyReport(.) provides a one-time. 
report of the same information provided by spy(). 


Data is gathered’ by an interrupt-level routine that is connected by 
spyClkStart( ) to the auxiliary clock. Currently, this facility cannot be used 
with CPUs that have no auxiliary clock. Interrupts that are at a higher level 
than the auxiliary clock's interrupt level cannot be monitored. 


EXAMPLE 
The following call: 


-> spy 10, 200 


will generate a report in the following format every 10 seconds, gathering 
data at the rate of 200 times per second. 
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MAME ENTRY TID PRI total % (ticks) delta % (ticks) 
eExcTask _GkCTESK inuSs o oS 3) os ¢ 9) 
tLogTask _logrask fa6eO 0 Ot ( 0) oF ( 0) 
tShell _shell e28a8 1 Ot ( 4) Ot ( 0) 
tRlogind _rlogind £08dc 2 Of ( 0) Ot ( 0) 
tRlogOutTask rlogOutTa @9300 2 2% ( 173) 2% ( 46) 
tRlogInTask rlogInTas e7f10 2 Of ( 0) Ot ( 0) 
tSpyTask _spyTask £fe9c s 1& ( 116) 1& ( 28) 
tDbxTask _dbxTask edbaé 20 O8 ( 0) O& ( 0) 
tet Task _netTask f3e2c 8050 Ot ( 4) Ot ( 1) 
tPortmapd _portmapd ef240 100 ot ( 0) Ot ( 0) 
KERMEL 1% ( 105) O% ( 10) 
INTERRUPT O& ( 0) O& ( 0) 
IDLE 95% ( 71990) 95% ( 1998) 
TOTAL 99% ( 8337) 98% ( 


2083) 


The “total” column reflects CPU activity since the initial call to spy() or the 
last call to spyClkStart{ )::The:delta‘:column.reflects activity since the pre- 
vious report. A call to spyReport(-) will.produce:a single report; however, 
the initial auxiliary clock interrupts and data collection must first be started 
using spyClkStart( ). 


Data collection/clock interrapts.and: periodic reporting are stopped by cal- 
ling: 


“> spyStop 
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NAME 
spyClkStart( ) - start collecting task activity data 


SYNOPSIS 
STATUS spyClkStart (intsPersec) | 
int intsPerSec; /* timer interrupt frequency, */ 
/* 0 = use default of 100 */ 


DESCRIPTION 
This routine begins data collection by enabling the auxiliary clock interrupts 
at a frequency of intsPerSec interrupts per second. If intsPerSec is omitted or 
zero, the frequency will be 100, or that rate closest to 100 ticks per second 
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(whether faster or slower) that the auxiliary clock cn support (see the 
module sysLib.c). Data from previous collections is cleared. 


For systems that cannot run the auxiliary clock at 100 interrupts per second, 
the default is the rate closest to 100 that the auxiliary clock can support. 
This value is determined by the auxiliary clock implementation in sysLib.c. 


RETURNS 
_ OK, or ERROR if the CPU has no auxiliary clock, or if task create and delete 
hooks cannot be installed. 


SEE ALSO 
spy Lib, sysAuxClkConneci{ ) 


NAME 

spyClkStop( ) - stop collecting task activity data 
SYNOPSIS 

VOID spyClkStop () 
DESCRIPTION 


This routine disables the auxiliary clock interrupts. Data collected remains 
valid until the next spyClkStart( ) call. 


RETURNS 
N/A 


SEE ALSO 
spyLib 


NAME 
spyReport( ) - display task activity data 


SYNOPSIS 
VOID spyReport () 


1 - 364 intel — | | Rev: 29 Aug 91 


Libraries (1) SpyLib 


DESCRIPTION 
This routine reports on data gathered at interrupt level for the amount of 
CPU time utilized by each task, the amount of time spent at interrupt level, 
the amount of time spent in the kernel, and the amount of idle time. Time is 
displayed in ticks and in percentage, and the data is shown since both the 
last call to spyClkStart() and the last spyReport(). If no interrupts have 
occurred since the last spyReport( ), nothing is displayed. 


RETURNS 
N/A 


SEE ALSO 
spyLib 


NAME 


spyTask( ) - run periodic task activity reports 
SYNOPSIS 
VOID spyTask (freq) 
int freq; /* reporting frequency, in seconds */ 
DESCRIPTION 


This routine is spawned as a task by spy() to provide periodic task activity 
reports. It prints a report, delays for the specified number of seconds, and 


repeats. 
RETURNS 
N/A 


SEE ALSO 
spyLib 


NAME 


spyStop() - stop spying and reporting 
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SYNOPSIS 
VOID spyStop () 

DESCRIPTION , 
This routine calls spyClkStop( ). Any periodic reporting by spyTask( ) is ter- 
minated. | 


RETURNS 
N/A 
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NAME 
spy() - begin periodic task activity reports 
SYNOPSIS 
VOID spy (freq, ticksPerSec) 
int freq; /* rveporting frequency, in seconds */ 
/* 0 = use default of 5 */ 
int ticksPerSec; /* interrupt clock frequency «/ 
/* 0 = use default of 100 tf 
DESCRIPTION : | | : 
| This routine collects task activity data and periodically runs spyReport( ). 
Data is gathered ticksPerSec times per second, and a report is made every freq 
seconds. If freq is zero, it defaults to 5 seconds. If ticksPerSec is omitted or 
zero, it defaults to 100, or a value as close to 100 as the auxiliary clock can 
support. This value is. determined by the implementation of the auxiliary 
clock in sysLib.c. . 
This routine spawns spyTask( ) to do the actual reporting. 
It is not necessary to call spyClkStart({ ) before running spy( ). 
RETURNS 
N/A 
SEE ALSO 
spyLib 
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NAME 
spyHelp( ) - display task monitoring help menu 
SYNOPSIS 
VOID spyHlelp () 
DESCRIPTION 
This routine displays a summary of spyLib utilities: 
spyHelp Print this list | 
spyClkStart [ticksPerfec) | Start task activity monitor running 
at ticksPergec ticks per second 
spyClkStop Stop collecting data 
spyReport Prints display of task activity 
statistics 
spyStop Stop collecting data and reports 
spy [freq[,ticksPerfec}] Start spyClkStart and do a report 


every freq seconds 
ticksPerSec defaults to 100. freq defaults to 5 seconds. 


RETURNS 
N/A 


SEE ALSO 
_ spyLib 
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NAME 


stdioLib - standard I/O library 


SYNOPSIS 
stdioInit{ ) - initialize stdioLib support 
isatty() - return whether the underlying vets is a tty device 
fclose()- empty stream buffers and close a file 
fdopen( ) - associate a stream with a file descriptor 
fgetc() - return the next character in an input stream 
fgets() - read a string from an input stream 
fflush() - write out any buffers on an output stream 
fopen() - open a stream ona file 
fprintf( ) - print a formatted string to a stream 
fputc( ) - append a character to an output stream 
fputs() - copy a NULL-terminated string to an output stream 
fread() - perform a buffered read 
freopen() - substitute a named file in place of an open stream 
fseek( ) - reposition a stream 
ftell() - return the current offset in a stream 
fwrite() - perform a buffered write 
gets() - read a string from the standard input stream 
getw( ) - read the next word (32-bit integer) from a stream 
puts() - copy a NULL-terminated string to the output stream 
putux ) - append a word (32-bit integer) to an output stream 
rewind( ) - position a stream at the beginning 
scanf( ) - read and convert characters from the standard input stream 
fscanf() - read and convert characters from an input stream 
setbuf{ ) - specify a buffer to be used on a stream 
setbuffer( ) - set a buffer to be used on a stream 
setlinebuf() - set the line buffering for either stdout or stderr 
ungetc( ) - push a character back into an input stream 
clearerr( ) - reset the error and end-of-file indicators 
feof() - determine if an end-of-file has been read 
ferror( ) - determine if an error has occurred while reading or writing 
fileno( ) - get the file descriptor associated with a stream 
getchar() - return the next character in the standard input stream 
putchar{( ) - append a character to the standard output stream 
getc( ) - return the next character in an input stream 
putc( ) - append a character to an output stream 


STATUS stdioInit () 
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BOOL isatty (fd) 

STATUS fclose (fp) 

Fils “idopen (id, type) 

int fgetc (fp) 

char *fgets (s, n, fp) 

int fflush (fp) 

FILE *fopen (filename, type) 
int fprintf£ (fp, fmt, ...) 

int fpute (c, fp) 

int fputs (s, fp) 

int fread (ptr, size, count, fp) 
FILE *freopen (filename, type, fp) 
STATUS fseek (fp, offset, ptrname) 
long ftell (fp) 

int fwrite (ptr, size, count, fp) 
char *gets (s) 

int getw (fp) 

int puts (s) 

int putw (w, fp) 

VOID rewind (fp) 

int scanf (fmt, ...) 

int fecanf (fp, fmt, ...) 

VOID setbuf (fp, buf) 

VOID setbuffer (fp, buf, size) 
VOID setlinebuf (fp) 

int ungetc (c, fp) 

VOID clearerr (fp) 

int feof (fp) 

BOOL, ferror (fp) 

int fileno (fp) 

int getchar () 

int putchar (c) 

int getc (fp) 

int pute (c, fp). 


DESCRIPTION : : 

_ This library provides a complete UNIX compatible standard I/O buffering 
scheme. It is beyond the scope of this manual entry to describe all aspects of 
the buffering — see the Vx960 Programmer's Guide: I/O System and the Ker- 
nighan & Ritchie C manual. This manual entry primarily highlights the 
differences between the UNIX and Vx960 standard I/O. 


VX_STOIO TASK OPTION 
Traditionally stdin, stdout, and stderr are macros, but, in Vx960, they are in 
fact variables. They will only be defined for the task context of tasks 
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spawned with the task option bit VX_STDIO. They are unique to each such 
task and correspond to the file descriptors 0, 1, and 2 in the basic I/O sys- 
tem. Their values are undefined when used at any other time, e.g., 
interrupt-level code or another task without the VX_STDIO option. 


NOTE: If a task will use stdin, stdout, or stderr, the task must be spawned 
with the VX_STDIO task option bit. 


The one exception is the use of the routine printf(), which, as explained 
below, does not actually use standard I/O buffering. 


FILE POINTERS 
The routine fopen( ) creates a file pointer. Use of the file pointer follows con- 
ventional UNIX usage. In a shared address space, however, and perhaps 
more critically, with the Vx960 system symbol table, tasks may not use each 
others’ file pointers, at least not without some interlocking mechanism. If it 
is necessary to use the same name for a file pointer but have incarnations for 
each task, then use task variables; see the manual entry for taskVarLib. 


FIOLIB 
Several routines normally considered part of standard I/O — printf(), 
sscanf(), and sprintf() — are not implemented in stdioLib; they are instead 
implemented in fioLib. They do not use the standard I/O buffering scheme. 
They are self-contained, formatted, but unbuffered I/O functions. This 
allows a limited amount of formatted I/O to be achieved without the over- 
head of the entire stdioLib package. 


TASK TERMINATION | 
When a task exits, unlike in UNIX, it is the responsibility of the task to 
fclose( ) its file pointers, except stdin, stdout, and stderr. If a task is to be ter- 
minated asynchronously, use kill( ) and arrange for a signal handler to clean 


up. 
INCLUDE FILES 
stdioLib.h, taskLib.h 


All the macros defined in stdioLib.h are also implemented as real functions 
so that they are available from the Vx960 shell. 


SEE ALSO | 
fioLib, ioLib, taskVarLib, sigLib, Kernighan & Ritchie C manual, 
Programmer's Guide: I/O System 
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NAME 
stdioInit( ) - initialize stdioLib support 
SYNOPSIS 
STATUS stdioInit () 
DESCRIPTION 
This routine must be called before using stdioLib buffering. If 
INCLUDE_STDIO is defined in configAILh, it is called by the root task 
usrRoot( ) in usrConfig.c. 
RETURNS 
OK, or ERROR if there is an error installing standard I/O facilities. 
SEE ALSO 
stdioLib 


NAME 


isatty() - return whether the underlying driver is a tty device 


SYNOPSIS 
BpooL isatty (fd) 
int fd; /* file descriptor to check */ 


DESCRIPTION 
This routine simply invokes the ioctl() function FIOISATTY on the specified 


fd. 


RETURNS : 
TRUE if the driver indicates a tty device, otherwise FALSE. 


SEE ALSO 
stdioLib 
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NAME 
fclose() - empty stream buffers and close a file 


SYNOPSIS 
STATUS fclose (fp) 
FILE ‘fp; /* stream */ 


DESCRIPTION 
This routine empties the buffer associated with a specified stream and closes 
the file. 


RETURNS 
OK if the buffers flush, or EOF if the Butlers cannot be written out or the file 


cannot be closed. 


SEE ALSO | 
stdioLib, fflush( ) 


NAME 
fdopen( ) - associate a stream with a file descriptor 


SYNOPSIS 


FILE *fdopen (fd, type) 
int fd; /* already open file deaccigise | ae 
char ‘type; /* mode to open file (must agree with open fd) */ 


DESCRIPTION A ESORE GG 
This routine associatés a‘stream with the file descriptor obtained by the rou- 
tines open() and creat( ). 7 


The mode type must be included because its status cannot be queried, and it 
must agree with the mode of the already open fd. 


RETURNS 
A stream pointer, or NULL if the fd is invalid. 


SEE ALSO 
stdioLib, fopen( ), freopen( ) 
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NAME 
fgetc() - return the next character in an input stream 
SYNOPSIS 
int fgetc (fp) 
FILE ‘*fp; /* stream */ 
DESCRIPTION 


This routine returns the next character from a specified input stream as an 
integer. It also moves the file pointer ahead one character in the stream. 
This routine is the same as getc( ), but is a genuine routine, not a macro. 


RETURNS 
The next character, or EOF on either end-of-file or an error. 


SEE ALSO 
stdioLib 


NAME 
fgets( ) - read a string from an input stream 


SYNOPSIS 
char *fgets (s, n, fp) 

char *s; /* buffer to hold characters.read */... . _. _.... |. 

int ny; /* number of bytes to read ~1 for’ newline */ 

FILE ‘fp; /* stream */ a ih. are 
DESCRIPTION ads, 
| This routine copies, at most, nL. charade: or.up-to the newline Caer: 
from the stream fp into the buffer 5:cFhe buffer:s.is NULL-terminiated. : 


RETURNS 
The NULL-terminated sane or NULL on either end-of-file or an error. 


SEE ALSO 
stdioLib, fopen( ), fread( ) 
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NAME 


fflush() - write out any buffers on an output stream 


SYNOPSIS 


int fflush (fp) 
FILE *fp; /* stream */ 


DESCRIPTION 


This routine writes the buffer associated with a specified stream. The 
stream remains open. 


RETURNS 


OK, or EOF if the the buffers cannot be written out. 


SEE ALSO 


stdioLib 


Pirhrrntdes 
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NAME 


fopen() - open a stream ona file 


SYNOPSIS 


FILE *fopen (filename, type) 
‘Char ‘filename; /* name of file */ 
char *type; /* mode to open file */ 


DESCRIPTION 


This routine opens a specified file and associates it with a stream. The 
returned file pointer is used to identify the stream with subsequent opera- 
tions. 


The type is a character string consisting of: 


r  - read 

w_ - write 

a - update, open for writing at the end, or create the file if it does not 
exist. 


In addition, a trailing + indicates that the file is to be opened for both read- 
ing and writing. 
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r+ - position at the beginning 
w+ - create or truncate 
a+ ~- position at the end 


Both reads and writes may be intermixed as long as an intervening fseek( ) 
or rewind( ) occurs. | 


RETURNS 
A file pointer, or NULL if the file cannot be opened. 


SEE ALSO 
stdioLib, freopen( ), fdopen( ) 


NAME 
fprintf() - print a formatted string to a stream 


SYNOPSIS 
int fprintf (fp, fmt, ...) 
FILE * f£p; /* output stream =/ 
char * fmt; /* format specification «/ 


DESCRIPTION 
This routine is the same as printf( ), except that it copies output to a speci- 
fied stream fp. 


NOTE a 
The standard output file pointer stdout is buffered; thus fflush() must be 
used to force output. 


RETURNS 
OK, or EOF if there is an error. 


SEE ALSO 
stdioLib, fopen( ) 
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NAME 
fputc( ) - append a character to an output stream 


SYNOPSIS 


int fputc (c, fp) 
int oc} /* character to append */ 
FILE ‘*fp; /* stream */ 


DESCRIPTION | 
This routine appends character c to a specified stream fp. It is the same as 


putc(), but is a genuine routine, not a macro. 


RETURNS 
The character written, or EOF if there is an error. 


SEE ALSO 
stdioLib, fopen( ), fyuts( ) 
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NAME 


fputs() - copy a NULL-terminated string to an output stream 


SYNOPSIS 


int fputs (s, fp) 
char ‘*s; /* string to copy:to output stream */. 
FILE *fp; /* output-stream 9; #8 °° #/ 


DESCRIPTION  “SSEDESCRIPEKH 0 sche 
-This routine copies thé NULL-terminated string s to a specified stream fp. 


RETURNS en ee | 
The last character written, or 0 if the stringisempty. - 


SEE ALSO 
stdioLib 
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int fread (ptr, size, count, fp) 


char *ptr; /* where to copy into */ 
unsigned sise; /* size of item «/ 
unsigned count; /* number of items «/ 
FILE *fp} /* input stream «/ 
DESCRIPTION 
This routine reads count items of data of size size from the stream fp into a 
block beginning at ptr. 
RETURNS 
The number of items read, or 0 on either end-of-file or an error. 
SEE ALSO 
stdioLib 
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NAME 
freopen( ) - substitute a named file in place-of:an:open stream:...:2: 6:0: 2 
SYNOPSIS 
FILE *freopen (filename, type, fp) 72% f2acpR {vise eety Cy fe 
Char ‘filename; /* new file eli heel ical “py feemiesr gdi ee 
char. *type; = /* mode to open® filers [is Reg fe oda t 
FILE *f£p}; /«* old stream wtief fa 
DESCRIPTION ee a 


This routine closes a stream and opens.a new. fileinits:place.- ie) 0. 


Typically freopen( ) is used to seas umurcn in-place; of oa standard pre- 
opened streams stdin, stdout, and stderr:-:: 


A file may be changed from unbuffered or line buffered to block buffered by 
using freopen(). A file can be changed from block buffered or line buffered 
to unbuffered by using freopen() followed by setbuf({ ) with a NULL buffer 


argument. 


ee 
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RETURNS 
The original value of the stream, or NULL if the file cannot be opened. 
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NAME 

fseek( ) - reposition a stream 
SYNOPSIS 

STATUS fseek (fp, offset, ptrname) 


FILE *f£p; /* stream */ 
long offset; /* byte to seek to */ 
int ptrname; /* type of seek (L_SET,L_INCR,L XTMD) */ 


DESCRIPTION 
This routine sets the position of the next I/O operation on a specified 
stream. The new position is at the signed distance offset bytes from either 
the beginning, the current position, or the end-of-file, according to the value 
of ptrname (0, 1, or 2). 


RETURNS 
OK, or ERROR if there are any improper seeks. 


SEE ALSO 
stdioLib, Iseek( ), fopen{ ) 
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NAME 


ftell( ) - return the current offset in a stream 


SYNOPSIS 
long ftell (fp) 
FILE ‘*fp; /* stream to report on */ 


DESCRIPTION 
This routine returns the current value, in bytes, of the offset from the begin- 
ning of the file associated with the specified stream. 
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RETURNS | 
The offset, or ERROR if the stream is invalid. 
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NAME 


fwrite( ) - perform a buffered write 
SYNOPSIS 
int fwrite (ptr, size, count, fp) 
char ‘ptr;  #$/* where to copy from */ 
unsigned size; /* size of item «/ 
unsigned count; /* number of items «/ 
FILE *fp; /* output stream «/ 
DESCRIPTION 


This routine appends, at most, count items of data of the size size, from the 
block beginning at pér to the stream fp. 


RETURNS 
The number of items written, or 0 if there is an error. 


SEE ALSO 
stdioLib, write( ), putc( ), puts() 


NAME 
_ gets() - read a string from the standard input stream 


SYNOPSIS 
char “gets (s) 
char ‘*s; /* buffer to hold characters read */ 


DESCRIPTION 
This routine reads a string from standard input up to a newline character 
and copies it into the buffer s. The string in s is NULL-terminated. 
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RETURNS 
The NULL-terminated string, or NULL on either end-of-file or an error. 


SEE ALSO 
stdioLib, fopen( ), fread( ) 


NAME 
getw( ) - read the next word (32-bit integer) from a stream 


SYNOPSIS 
int getw (fp) 
VILE ‘fp; /* input stream */ 


DESCRIPTION 
This routine reads the next 32-bit quantity from a specified stream. It 
returns EOF on an. end-of-file or an error; however, this is also a valid 
integer, thus feof({ ):and ferror( ) must be used to check for a true end-of-file. 


RETURNS 
A 32-bit number from the stream, or EOF on either end-of-file or an error. 


SEE ALSO 
stdioLib, fopen( ), getc( ) 
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NAME PP ie pao . 


a puts()- copy a NULL-terminated stririg tothe output stream 


SYNOPSIS 
int puts (s) - 

a char ‘*s; /* string to copy to output */ 

DESCRIPTION | 
This routine is the same as fputs(), but adds a newline at the end of the 
string. . 


RETURNS 
The last character written (newline), or EOF. 
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SEE ALSO 
stdioLib, fputs( ), fopen( ), gets() 
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NAME 
putur ) - append a word (32-bit integer) to an output stream 


SYNOPSIS 
int putw (w, fp) 
int wy; /* word (32-bit integer) */ 
FILE ‘fp; /* stream */ 


DESCRIPTION 
This routine writes the 32-bit quantity: w.to a specified stream. 


RETURNS ; 
The value written. 


SEE ALSO 
stdioLib 


eed ’ see 


NAME | os 
rewind( ) - position a stream at the beginging 3 - gusishos a steerer re ptt J 
SYNOPSIS oe era 
VOID rewind (fp) Week 
FILE *£p; ° 
DESCRIPTION | Saeed 2 
This routine sets the position of the néxtd /@rSperation‘to the: beginning: of-a= 
specified stream. It is equivalent to:. syeciiits eet 
fseek (fp, OL, 0); pee he ge 
RETURNS 
N/A 


Rev: 29 Aug 91 intel 1 - 38] 


oe 
tet 


Vx960 5.0 — Reference Manual 


SEE ALSO 
stdioLib, fseek( ), ftell( ), fopen() 
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NAME 
scanf() - read and convert characters from the standard input stream 
SYNOPSIS 
int scanf (fmt, ...) 
char *fmt; /* the format string «/ 
DESCRIPTION 


This routine reads characters from the standard input stream, interprets 
them according to the format in string fmt, and assigns values to variables 
pointed to by va_alist. 


See the manual entry for sscanf() for a full description of format specifica- 
tion. | 


RETURNS 
The number of items scanned, or EOF on end-of-file. 


SEE ALSO 
stdioLib, fopen( ), fscanf(), sscanf(), Kernighan & Ritchie C manual 


NAME 
fscanf() - read and convert characters from an input stream 
SYNOPSIS 7 
int fecanf (fp, fm, ...) 
FILE ‘fp; /* stream to read from */ 
char ‘fet; /* the format string */ 
DESCRIPTION 


This routine reads characters from a stream, interprets them according to the 
format in string fmt, and assigns values to arguments starting with the one 
pointed to by va_list. 
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See the manual entry for sscanf() for a full description of format specifica- 
tion. 


The number of items scanned, or EOF on end-of-file. 


SEE ALSO 
stdioLib, fopen( ), sscanf(), Kernighan & Ritchie C manual 
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NAME 
setbuf() - specify a buffer to be used on a stream 


SYNOPSIS 
VOID setbuf (fp, buf) 
FILE *fp; /* stream */ 
char “buf; /* buffer to be used for stream; WULL = unbuffered */ 


DESCRIPTION 
This routine specifies a character array buf to be used on a stream in place of 
the automatically allocated buffer. If buf is NULL, the stream is unbuffered. 
This routine must be called before reading or writing on a stream. 


The array must be of size BUFSIZE. The routine setbuffer ) allows a user- 
specified buffer size. 


RETURNS 
N/A 


SEE ALSO 
stdioLib, freopen( ), setbuffer() 
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NAME 
setbuffer( ) - set a buffer to be used ona stream 


SYNOPSIS 
VOID setbuffer (fp, buf, size) 
FILE ‘*fp; /* stream */ 
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char ‘buf; /* buffer to be used for stream; WULL = unbuffered */ 
int size; /* size of buffer */ 


DESCRIPTION 
This routine specifies a character array buf to be used on a stream in place of 
the automatically allocated buffer. If buf is NULL, the stream is unbuffered. 
_ This routine must be called before reading or writing on a stream. The rou- 
tine setbuf( ) may be used if the buffer size is to be of size BUFSIZE. 


RETURNS 
N/A 


SEE ALSO 
stdioLib, freopen( ), setbuf( ) 


NAME 


setlinebuf( ) - set the line buffering for either stdout or stderr 


SYNOPSIS 
VOID setlinebuf (fp) 
FILE ‘*fp; /* stream */ 


DESCRIPTION 
This routine changes.stdout or-stderr from block buffered or unbuffered to 
line buffered. reer taal =e earns ‘), it can be-used at any. time the 
stream is active. 


A stream can be change from-unbutered orline: eeraneen to. block. aaah 


NULL. 


RETURNS y 2 
N/A - 


SEE ALSO 
stdioLib, freopen(), setbuf{ ) 
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NAME 
ungetc( ) - push a character back into an input stream 


SYNOPSIS 


int ungetc (c, fp) 
int oc} /* character to push 
FILE *fp; /* stream */ 


DESCRIPTION 
This routine pushes c back into an input stream. The next call to getc() will 
return c. Only a one-character push is guaranteed. 


RETURNS 
The character c, or EOF if the character cannot be pushed back. 


SEE ALSO 
stdioLib, fopen( ), getc( ) 


NAME 
clearerr( ) - reset the error and end-of-file indicators , 


SYNOPSIS 
VOID clearerr (fp) - ; 
FILE *fp; /* stream «/ ae “lie « ; a 7 


DESCRIPTION eee ste hd 
This routine clears the error and: endo6 file indicators Ure sepeciAeti steers aitiiicindicate 


RETURNS | 
N/A | 


SEE ALSO 
stdioLib 
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NAME 
feof() - determine if an end-of-file has been read 


SYNOPSIS 
int feof (fp) 
FILE ‘fp; /* stream */ 


DESCRIPTION | 
This routine returns TRUE if an end-of-file has been read from a specified 
input stream. The end-of-file indication remains until the stream is closed or 


is reset by clearerr{ ). 


RETURNS 
TRUE if an end-of-file has been read, otherwise FALSE. 


SEE ALSO 
stdioLib, clearerr( ), ferror() 


NAME | 
ferror( ) - determine if an error has occurred while reading or writing 


SYNOPSIS 
pOOL ferror (fp) 
FILE ‘fp; /* stream */ 


DESCRIPTION 
This routine returns TRUE if an error has occurred while reading from or 
writing to a specified stream. The error remains until the stream is closed or 
is reset by clearerr( ). 


RETURNS | 
TRUE if an error has occurred, otherwise FALSE. 


SEE ALSO 
stdioLib, clearerr( ), feof() 
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NAME 
fileno( ) - get the file descriptor associated with a stream 


SYNOPSIS 
int fileno (fp) 
FILE *fp; /* stream */ 


DESCRIPTION 
This routine returns the file descriptor associated with a specified stream. 


RETURNS 
The file descriptor for the specified stream. 


SEE ALSO 
stdioLib, open( ) 
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NAME 
getchar( ) - return the next character in the standard input stream 


SYNOPSIS 
int getchar () 


DESCRIPTION 
This routine returns the next character in the standard input stream. It is 
equivalent to: 


getc (stdin); 


RETURNS 
The next character in the standard input stream. 


SEE ALSO 
stdioLib 
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NAME 


putchar( ) - append a character to the standard output stream 


SYNOPSIS 
int putchar (c) 
int c) /* character to output */ 


DESCRIPTION | 
This routine appends a character to the standard output stream. It is 
equivalent to: 


putc (c, stdout); 
This function replicates the macro by the same name and is useful for invo- 
cations from the shell. 


RETURNS 
The character written, or EOF if there is an error. 
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‘NAME : 
— getc() - return the next character in an input stream . 

SYNOPSIS 

int getc (fp) | 
a ; FILE ‘fp; /* stream */ te 

DESCRIPTION | 
This routine returns the next character in a specified input stream. It repli- 
cates the macro by the same name and is: useful for invocations from the 
shell. 

RETURNS 
The next character, or EOF on either end-of-file or an error. 

SEE ALSO 
stdioLib 
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NAME 
putc() - append a character to an output stream 


SYNOPSIS 
int putc (c, fp) 
int oc} /* character */ 
FILE ‘fp; /* stream */ 


DESCRIPTION 
This routine appends a character to a specified output stream. It replicates 
the macro by the same name and is useful for invocations from the shell. 


RETURNS 
The character written, or EOF if there is an error. 


SEE ALSO 
stdioLib 
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NAME 


strLib - string subroutine library 


SYNOPSIS — 
strcat() - append second string to first 
strchr() - return pointer to first occcurrence of char in string 
strcmp() - compare two strings lexicographically 
strcpy() - copy second string to first 
strcspn() - return number of initial chars of second not found in first 
strerror( ) - return pointer to error message string for argument 
strlen() - return length of string 
strncat() - append up to n chars of second string to first 
strncmp() - compare upto n chars of two strings lexicographically 
strncpy() - copy upton chars of second string to first 
strpbrk( ) - returnt pointer to first char of second string found in first 
strpos() - return index of first occurrence of char in string 
strrchr() - return pointer to last occurrence of char in string 
strrpbrk{ ) - return pointer to last char of second char found in first 
strrpos() - return index of last occurrence of char in string 
strspn() - return number of initial chars in first string found in second 
strstr() - return pointer to first occurrence of second string in first 
strtok() - return pointer substring of first delimited by chars in second 
strcoll() - like strcmp but uses locale-specific collating rules 
strxfrin() - transforms upto n chars so strcmp(t1, t2) == strcoll(s1, s2) 
index() -sameas ANSI strchr (non-ANSI) 
rindex() - same as ANSI strrchr (non-ANSI) 


char * strceat (char *sl1, const char “s2) 
char * strchr (const char *s, int n) 

strcmp (const char “sl, const char “s2) 
strcepy (char “sl, const char *s2) 

strcspn (const char “sl, const char *s2) 
strerror (int e) 

strlen (const char *s) 

strncat (char *sl, const char “s2, size_t n) 
int strncap (const char “sl, const char *s2, size t n) 
char * strncpy (char *sl, const char *s2, size t) 
char * strpbrk (const char “sl, const char *s2) 
int strpos (const char *s, char c) 

char * strrchr (const char *s, int n) 

char * strrpbrk (const char *sl, const char “s2) 
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int stxrrpos (const char *s, char c) 

size t strspn (const char *sl, const char “s2) 
char * strstr (const char ‘a1, const char *s2) 
char * strtok (char *sl, const char *s2) 

int strooll (const char *sl, const char “s2) 
size t strxfrm (char *sl, const char “s2, size_t n) 
char * index (const char *s, int c) 

char * rindex (const char *s, int c) 


DESCRIPTION 


This library contains routines that duplicate the ANSI-compliant versions of 
the UNIX string processing package. The functions operate on null- 
terminated strings of characters. They do not. check for the overflow of any 
resulting strings. 


NOTE 
These routines actually resolve to those supplied with the compiler tool set, 
for example the Intel GNU/960 tool set. The documentation for these rou- 
tines is not included as part of Vx960, but they are documented in the 
GNU/960 documentation set in the book “‘C, A Reference Manual,” by 
Samuel P. Harbison and Guy L. Steele Jr. (The routines strcoll() and 
strxfrm() only appear in the Third Edition and later.) | 

INCLUDE FILE 
-_#include “strLib.h’ 

SEE ALSO 


bLib, “C, A Reference Manual,’ Harbison and Steele, Prentice Hall 
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swapLib - byte swapping functions for little endian machines 


SYNOPSIS | 
htonl( ) - convert long (32bit) from host to network byte order. 
ntohl( ) - convert long (32bit) from network to host byte order. 
htons( ) - convert long (16bit) from host to network byte order. 
ntohs() - convert long (16bit) from network to host byte order. 


UINT32 htonl (x) 
UINT32 ntohl (x) 
UINT16 htons (x) 
UINT16 ntohs (x) 


DESCRIPTION 
This library contains functions to convert long (32-bit) and short (16-bit) 
quantities from processor (host) byte order to network byte order, and visa- 
versa. These functions duplicate the macros of the same name for those 
who do not include the header file in.h. 


INCLUDE FILE 
in.h 


SEE ALSO 
Network. 
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NAME : 
htonl() - convert long (32 bit) from host to network byte order. 
SYNOPSIS | 


UINT32 htonl (x) 
UINT32 x} 


DESCRIPTION 
Host to net byte swap function. On little endian processors such as the 960 
this converts from little endian to big endian. Duplicates macro of the same 
name in the header file in.h. 
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RETURNS 

Input value in network byte order 
SEE ALSO 

swapLib, htons( ) 
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NAME 
ntohlI() - convert long (32 bit) from network to host byte order. 


SYNOPSIS 
UINT32 ntohl (x) 
UINT32 x3 


DESCRIPTION 
Same code as htonl(), but duplicated to save funtion call overhead. Dupli- 
cates macro of the same name in the header file in.h. 


RETURNS 
Input value in host byte order 


SEE ALSO 
swapLib, htonl( ) 
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NAME eae 
htons() - convert short (16 bit) from host to network byte order. 
SYNOPSIS 
UINT16 htons (x) 
UINT16 x; 
DESCRIPTION : 


Converts short (16bit) ints from processor (host) byte order to network byte 


order. On the i960 microprocessor, this converts from little endian to big 


endian byte orders. Duplicates macro of the same name in the header file 
in.h. 7 
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RETURNS | 
Input value in network byte order. 


SEE ALSO 


swapLib, htonI( ) 
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NAME 
— ntohs() - convert short (16 bit) from network to host byte order. 


SYNOPSIS 
UINT16 ntohs (x) 
UINT16 x; 


DESCRIPTION 
Same as htons, but duplicated to save function call. Duplicates macro of the 


same name in the header file in.h. 


SEE ALSO 
swapLib, htons( ) 


RETURNS 
Input value in host byte order. 
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NAME 
sym Lib - symbol table subroutine library 
SYNOPSIS 


symLibInit( ) - initialize the symbol table library 

symTblCreate( ) - create a symbol table 

symIblDelete( ) - delete a symbol table 

symAdad{ ) - create and add a symbol to a symbol table 
symRemove() - remove a symbol from a symbol table 
syitFindByName( ) - look up a symbol by name 
symFindByNameAndType( ) - look up a symbol by name and type 
symFindByValue( ) - look up a symbol by value 
symFindByValueAndType( ) - look up a symbol by value and type 
symEach( ) - call a routine to examine each entry in a symbol table 


STATUS symLibInit () 

SYMTAB ID sywiblCreate (hashSizelLog2, sameNameOk, symPartId) 

STATUS symiblDelete (symTblId) 

STATUS symAdd (symEblId, name, value, type) 

STATUS symRemove (symIblId, name, type) 

STATUS sym indByName (symIblId, name, pValue, pType) 

STATUS sywFindSyNameAndType (symIblid, nase, pValue, prype, sTyps, mask) 

STATUS sywFindByValue (symIbliId, value, name, pValue, pType) 

STATUS symFindByValueAndType (symTblid, value, name, pValue, ‘PTYPS, sType, mask) 
SYMBOL *symEach (symTblid, routine, routineArg) | 


DESCRIPTION 
This library provides facilities for managing symbol tables. A symbol table 
associates a name and type with a value. A name is simply an arbitrary, 
null-terminated string. A symbol type is a small integer (typdef 
SYM_TYPE), and its value is a character pointer. Though commonly used as 
the basis for object loaders, symbol tables may be used whenever efficient 
association of a value with a name is needed. 


Tables are created with symTblCreate( ), which returns a symbol table ID. 
This ID serves as a handle for symbol table operations, including the adding 
to, removing from, and searching of tables. All operations on a symbol table 
are interlocked by means of a mutual-exclusion semaphore in the symbol 
table structure. Tables are deleted with symTblDelete( ). 


Symbols are added to a symbol table with symAdd(). Each symbol in the 
symbol table has a name, a value, and a type. Symbois are removed from a 
symbol table with symRemove( ). 
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Symbols can be accessed by either name or value. The routine 
symFindByName() searches the symbol table for a symbol of a specified 
name. The routine symFindByValue() finds the symbol with the value 
closest to a specified value. The routines symFindByNameAndType( ) and 
symFindByValueAndType( ) allow the symbol type to used as an additional 
criterion in the searches. : 


Symbols in the symbol table are hashed by name into a hash table for fast 
look-up by name, e.g., by symFindByName( ). The size of the hash table is 
specified during the creation of a symbol table. Look-ups by value, e.g., 
symFindByValue( ), must search the table linearly; these look-ups can thus 
be much slower. 


The routine symEach() allows each symbol in the symbol table to be exam- 
ined by a user-specified function. 


Name clashes occur when a symbol added to a table is identical in name and 
type to a previously added symbol. Whether or not symbol tables can 
accept name clashes is set by a parameter when the symbol table is created 
with symTblCreate(). If name clashes are not allowed, symAdd() will 
return an error if there is an attempt to add a symbol with identical name 
and type. If name clashes are allowed, adding multiple symbols with the 
same name and type will be permitted. In such cases, symFindByName( ) 
will return the value most recently added, although all versions of the sym- 
bol can be found by symEach( ). 


INCLUDE FILE 


NAME 


symLib.h 
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symLibInit{ ) - initialize the symbol table library 


SYNOPSIS 


STATUS sywLibInit () 


DESCRIPTION 


This routine initializes the symbol table package. If INCLUDE_SYM_TBL is 
defined in configAlI.h, it is called by usrRoot( ) in usrConfig.c. 
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RETURNS 
OK, or ERROR if the library could not be initialized. 


SEE ALSO 
symLib 


NAME 
symTblCreate( ) - create a symbol table 


SYNOPSIS 
SYMTAB ID symTblCreate (hashSizelLog2, sameNaweOk, symPartId) 
int hashSizelog2; /* size of hash table as a power of two */ 
BOOL semeNameO0k } /* allow two symbols of same name and type */ 
PART ID symPartId; /* memory partition ID for symbol allocation */ 


DESCRIPTION 
This routine creates and initializes a symbol table with a hash table of a 
specified size. The size of the hash table is specified as a power of two. For 
example, if hashSizeLog2 is 6, a 64-entry hash table is created. 


If sameNameOk is FALSE, attempting to add a symbol with the same name 
and type as an already-existing symbol results in an error. 


Memory for storing symbols as they are added to the symbol table will be 
allocated from the memory partition symPartId. The ID of the system 
memory partition is stored in the global variable memSysPartld, which is 
declared in memLib.h. | 


RETURNS 
Bynes) table ID, or NULL ifn memory: is insufficient. - 


SEE ALSO 
symLib 
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NAME 

symTblDelete( ) - delete a symbol table 
SYNOPSIS 


STATUS syurblDelete (symTbl1Id) 
SYMTAB ID symIblid; /* ID of symbol table to delete */ 


DESCRIPTION 
This routine deletes a specified symbol table. It deallocates all associated 
memory, including the hash table, and marks the table as invalid. 


Deletion of a table that still contains symbols results in ERROR. Successful 
deletion includes the deletion of the internal hash table and the deallocation 
of memory associated with the table. The table is marked invalid to prohibit 
any future references. 


RETURNS 
OK, or ERROR if the symbol table ID is invalid. 


SEE ALSO 
symLib 


NAME . 


symAdd( ) - create and add a symbol to a symbol table 
SYNOPSIS | 
STATUS symAdd (symfblid, name, value, type) - 7 | Ee 
SYMTAB ID symTblId; /* symbol table to add oe to “/ 
char *name} /* pointer to symbol name string */ 
char *value; /* symbol address */ 
SYM_TYPE type; /* symbol type */ 
DESCRIPTION 


This routine allocates a symbol name and adds it to a specified symbol table 
symIblld with the specified parameters value and type. 


RETURNS 
OK, or ERROR if the symbol table is invalid or there is insufficient memory 
for the symbol to be allocated. 
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NAME 
symRemove( ) - remove a symbol from a symbol table 


SYNOPSIS | 
STATUS symRemove (symTblid, name, type) 
SYMIAB ID sywEblid; /* symbol table to remove symbol from */ 


char *name} /* name of symbol to remove */ 
SYM_TYPE type; /* type of symbol to remove */ 
DESCRIPTION 


This routine removes a symbol of bs sihcidane name and type from a specified 
symbol table. The yao is deallocated if found. 


RETURNS | 
OK, or ERROR if the symbol is not found or could not be deallocated. 


SEE ALSO 
symLib 
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NAME 
symFindByName( ) - look up a symbol by name 


SYNOPSIS 
STATUS sywFindByName (symIblid, name, pvalue, pType) 
SYMTAB ID symTblid; /* ID of symbol table to find name in */ 


char *name} /* symbol name to look for */ 

char **pValue; /* pointer where to return symbol value */ 

SYM TYPE ‘pType; /* pointer where to return symbol type */ 
DESCRIPTION 


This routine searches a symbol table for a symbol matching a specified 
name. If the symbol is found, its value and type are copied to pValue and 
pType. If multiple symbols have the same name but differ in type, the rou- 
tine chooses the matching symbol most recently added to the symbol table. 
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RETURNS 
OK, or ERROR if the symbol table ID is invalid or the symbol is not found. 
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NAME 
symFindByNameAndType( ) - look up a symbol by name and type 


SYNOPSIS 
STATUS sywFindByMameAndType (symIblid, name, pValue, pType, sType, mask ) 

SYMTAB_ID symTbliId; /* ID of symbol table to find name in */ 
char *name } /* syabol name to look for */ 
char **pValue; /* pointer where to return symbol value */ 
SYM TYPE ‘*pType; /* pointer where to return symbol type */ 

_SYM_TYPE sType; /* symbol type to look for */ 
SYM TYPE mask; /* which bits in <sType> to pay attention to */ 


DESCRIPTION 
This routine searches a symbol table for a symbol matching both name and 
type (name and sType). If the symbol is found, its value and type are copied 
to pValue and pType. The mask parameter can be used to match sub-classes of 


type. 


RETURNS | 
OK, or ERROR if the symbol table ID is invalid or the symbol is not found. 


SEE ALSO 
symLib 
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NAME 
symFindByValue( ) - look up a symbol by value 


SYNOPSIS 
STATUS sywFindByValue (symTblid, value, name, pValue, pType) 
SYMTAB_ID symIblid; /* ID of symbol table to find name in */ 
int value; /* value of symbol to find */ 


1 - 400 Intel | | Rev: 29 Aug 91 


Ubraries (1) SymLib 


char "name; /« pointer where to return symbol name string */ 

int *p¥Value; /* pointer where to return symbol value */ 

SYM TYPE ‘pType; /*« pointer where to return symbol type */ 
DESCRIPTION 


This routine searches a symbol table for a symbol matching a specified 
value. If there is no matching entry, it chooses the table entry with the next 
lower value. The symbol name (with terminating EOS), the actual value, 
and the type are copied to name, pValue, and pType. 


RETURNS 
OK, or ERROR if value is less than the lowest value in the table. 


SEE ALSO 
symLib 


NAME 
symFindByValueAndType( ) - look up a symbol by value and type 


SYNOPSIS : | 
STATUS synF indByValueAndType (symiblid, value, name, pValue, pType, sType, mask) 
SYMTAB_ ID syeTbliId; /* ID of symbol table to find name in */ . | 


int value; /* value of symbol to find */ 
Char * DAMS } /* pointer where to return symbol: name string:*/ 22 <== 
int * pValue; /* pointer where to return. symbol value.-*/ -=-25 £5 :-: 
SYM_TYPE * pType; . /* pointer where.to return: symbol : type: ef : 
SYM_TYPE = BT ype} /* symbol.type to look for. */ -- =. - , Piece 
SYM TYPE mask; —«_ /* which bits:in:<stype> to pay attention to me ee 
daaedab dle ~~ peerets. 


This routine searches a symbol tatites i ilemeih aii both value: andy bc ¢: 
type (value and sType). If there ismo{matching eritry;. it chooses the: table::* of 
entry with the next lower value. -Thesymbel:name (with terminating EOS);:-: -- <:= 
the actual value, and the type are:copied to name, pValue, and pType. The | 
mask parameter can be used to match sub-classes of type. 


RETURNS 
OK, or ERROR if value is less than the lowest value in the table. 


SEE ALSO 
symLib 
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NAME | | 
symEach( ) - call a routine to examine each entry in a symbol table 
SYNOPSIS — 
SYMBOL, “symEach (symIblid, routine, routineArg) 
SYMTAS ID sywTblid; /* pointer to symbol table «/ 
FUSCPTR routine; /* the routine to call for each table entry */ 
int routineArg; /* arbitrary user-supplied argument «/ 
DESCRIPTION 


This routine calls a user-supplied routine to examine each entry in the sym- | 
bol table; it calls the specified routine once for each entry. The routine 
should be declared as follows: 


BOOL routine (name, val, type, arg) 


char ‘name; /* entry name * 
int. val; /* value associated with the entry * 
SYM TYPE type; /* entry type * 
int arg; /* arbitrary user-supplied argument * 


The user-supplied routine should return TRUE if symEach{ ) is to continue 
calling it for each entry, or FALSE if it is done and symEach( ) can exit. 


RETURNS = 
A pointer to the last symbol reached, or NULL if all symbols are reached. 


SEE ALSO 
symLib 
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NAME 
taskArchLib - architecture specific task management routines for kernel 


SYNOPSIS 
taskRegsInit( ) - initialize a task's registers 
taskArgsSet( ) - set a task’s arguments 
taskArgsGet( ) - get a task’s arguments 
taskRegsShow( ) - display contents of a task’s registers 
taskPCWSet( ) - set task proccessor control word 
taskACWSet( ) - set task arithmetic control word 
taskTCWSet{ ) - set task trace control word 
taskRinValueSet{ )taskRtnValueSet - 
taskStackAllot( ) - allot memory from caller's stack 
taskRegsStackToTcb( ) - move the i960 local registers from stack to tcb. 
taskRegsTcbToStack( ) - move the i960 local registers from tcb to stack. 


VOID taskRegsInit (pcb, pStackBase) | 

VOID taskArgsSet (pTcb, pStackBase;-pArgs) 

VOID taskArgsGet (pTcb, pGtackBase, pArgs) 

VOID taskRegsShow (tid) re 

STATUS taskPCWSet (tid, pow) r 

STATUS taskACWSet (tid, acw) Psi a gee * 

STATUS taskTCWSet (tid, tow) =. : 

VOID taskRtnValueSet (pTcb, value) 

void *taskStackAllot (tid, nBytes)si2 ““cccctcc 
VOID taskRegsStackToTcb (pTcb) Serie Siemens ae 
VOID taskRegsTcbToStack (pTcb) ="* - 


DESCRIPTION oe DESERT | 
This library provides an interface JGSBEUspecifietabkemanazemient: youtines#<= Het 
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NAME 
taskRegsInit( ) - initialize a task’s registers 


SYNOPSIS 


VOID taskRegsInit (piIcb, pétackBase) 
WIND _TCB *pTchb; /* pointer TCB to initialize */ 
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char “pStackBase; /* bottom of task’s stack */ 


DESCRIPTION 
This routine initializes the task’s local and global registers to zero, the rip, fp, 
and sp to stack addresses (and initializes their locations within the stack 
frame as well), and initializes the tcw, acw, and pew for normal operation. 


SEE ALSO 
taskArchLib 


NAME 


taskArgsSet( ) - set a task’s arguments 


SYNOPSIS 


VOID taskArgsSet (pTcb, p@tackBase, pArgs) 
WIND TCB * pTcb; /* pointer TCB to initialize */ 
char * pStackBase; /* bottom of task’s stack */ 
int pargs[]; /* array of startup arguments */ 
DESCRIPTION 


This routine puts the task’s arguments into global registers as well as saving 
them in stack variables in preparation for calling the task entry point. 


SEE ALSO 
taskArchLib 


NAME... 
taskArgsGet( ) - get a task’s arguments 


SYNOPSIS 
VOID taskArgsGet (pTcb, pStackBase, pArgs) 
WIMD_TCB * pfcb; /* pointer TCB to initialize */ 
char * pGtackBase; /* bottom of task’s stack */ 
int pArgs[]} /* array of arguments to fill */ 
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DESCRIPTION 

Fills the pArgs array from the stack available as saved by taskArgsSet( ). 
SEE ALSO 

taskArchLib, taskArgsSet( ) 
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NAME 
taskRegsShow( ) - display contents of a task’s registers 


SYNOPSIS 
VOID taskRegsShow (tid) 
int tid; /* task ID */ 


DESCRIPTION 
This routine prints to standard out the contents of a task’s registers. 


EXAMPLE 
-> taskRegsShow (taskNameToId ("fMetTask”") ) 


CAVEAT 
Since taskRegsShow gets its information from the TCB, this will only be 
_accurate up to the point that the TCB was last saved at task-switch time. 
Therefore, it may not be meaningful for a task to attempt to examine its own 
registers. 


SEE ALSO 
taskArchLib 


NAME 
taskPCWSet( ) - set task proccessor control word 


SYNOPSIS 
STATUS taskPCWSet (tid, pow) 
int tid; /* task id */ 
UINT32 pow; /* new PCH */ 
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DESCRIPTION 
This routine sets the processor control word (PCW) of a task not running 
(i.e. the task ID must NOT be that of the calling task). It is used by the 
debugging facilities to set the trace bit in the PCW of a task being single- 


stepped. 


RETURNS 
OK or ERROR if invalid task id 


SEE ALSO | 
taskArchLib 


NAME 
taskACWSet( ) - set task arithmetic control word 
SYNOPSIS 
STATUS taskACWSet (tid, acw) 
int tid; /* task id */ 
UINT32 acw; . /* new ACH */ 
DESCRIPTION 
This routine sets the arithmetic control word (ACW) of a task not running 
(i.e. the task ID must NOT be that of the calling task). It is used by the 
debugging facilities to.set the ‘no imprecise faults” bit in the ACW of a 
task being single-stepped. 
RETURNS — _-% ¥ 
OK or ERROR if invalid task id | 
SEE ALSO .wenze SEE ALD * & 
taskArchLib | 


NAME 


taskTCWSet( ) - set task trace control word 
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SYNOPSIS 
STATUS taskTCWSet (tid, tow) 
int tid; /* task id */ 
UINT32 tow; /* new TCH */ 
DESCRIPTION 


This routine sets the trace control word (TCW) of a task not running (i.e. the 
task ID must NOT be that of the calling task). It is used by the debugging 
facilities to set mask trace bits in the TCW of a task being debugged. 


RETURNS 
OK or ERROR if invalid task id 


SEE ALSO 
taskArchLib 


NAME 
taskRinValueSet{ )taskRtmValueSet - 
SYNOPSIS 
VOID taskRtnValueSet (pTcb, value) 
WIND _TCB * pcb; /* pointer to TCB */ 
INT32_ value; /* value to set */ 
DESCRIPTION 
Set the return value of function in the given TCB. 
SEE ALSO 


taskArchLib 


+0 


NAME 
taskStackAllot{ ) - allot memory from caller's stack 


SYNOPSIS 
void *taskStackAllot (tid, nBytes) 
int tid; /* task whose stack will be allotted from */ 
unsigned nBytes; /* number of bytes to allot */ 
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DESCRIPTION 
This routine allots the specified amount of memory from the end of the 
caller's stack. This is a non-blocking operation. This routine is utilized by 
task create hooks to allocate any additional memory they need. The 
memory cannot be added back to the stack. It will be reclaimed as part of 
the reclamation of the task stack when the task is deleted. 


Note that a stack crash will overwrite the allotments made from this routine 
because all portions are carved from the end of the stack. Use checkStack to 
diagnose possible task stack overflows. 


This routine will return NULL if requested size exceeds available stack 
memory. 


RETURNS 
pointer to block, or 
NULL if unsuccessful. 


SEE ALSO 
taskArchLib, checkStack 
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NAME | 
taskRegsStackToTcl{ ) - move the i960 local registers from stack to TCB. 
SYNOPSIS 
| VOID taskRegsStackToTcb ' (ered) 
WIND_TCB *pTcb; wigcciovra tse fw pointer to task .TCB */. 
DESCRIPTION ca | 


Used by taskRegsShoed. kag gan d:the:debingifacilitiesto:piabtocal abs 
registers, which may-have been: cdched -on chip, into:the task's TCB.". | 


SEE ALSO ; 
taskArchLib - 
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NAME 
taskRegsTcbToStack( ) - move the i960 local registers from TCB to stack. 
SYNOPSIS 
VOID taskRegsTcbToStack (pTcb) 
WIMD_TCB *pTcb; /* pointer to task TCB */ 
DESCRIPTION 


Used by the task switching and debug facilities to move the local registers 
from the tasks TCB to the stack from which they will be loaded when the 
task resumes. 


SEE ALSO 
taskArchLib 
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NAME 
taskHookLib - task hook library 


SYNOPSIS | 
taskCreateHookAdd{ ) - add a routine to be called at every task create 
taskCreateHookDelete( ) - delete a previously added task create routine 
taskCreateHookShou  ) - show the list of task create routines 
taskSwitchHookAdd( ) - add a routine to be called at every task switch 
taskSwitchHookDelete( ) - delete a previously added task ewan routine 
taskSwitchHookShow( ) - show switch routines 
taskDeleteHookAdd( ) - add a routine to be called at every task delete 
taskDeleteHookDelete( ) - delete a previously added task delete routine 
taskDeleteHookShow({ ) - show the delete routines 


STATUS taskCreateBookAdd (createHook) 
STATUS taskCreatelookDelete (createlicok) 
VOID taskCreateHookShow () 

STATUS taskSwitchHookAdd (switchHook) 
STATUS taskSwitchHookDelete (switchHook) 
VOID taskSwitchHookShow () 

STATUS taskDeletelookAdd (deleteHook) 
STATUS taskDeleteHookDelete (deletelook) 
VOID taskDeleteHookShow () 


DESCRIPTION 

This library provides routines for adding extensions to the Vx960 tasking 
facility. To allow task-related facilities to be added to the system without 
modifying the kernel, the kernel provides call-outs every time a task is 
created, switched, or deleted, which allow additional routines, or ‘“‘hooks,’ 
to be invoked whenever these events occur. The hook management rou- 
tines below allow hooks to be dynamically added to and deleted from the 
current lists of create, switch, and delete hooks: 


taskCreateHookAdd( ) and taskCreateHookDelete( ) 
- Add and delete routines to be called when a task is created. 


taskSwitchHookAdd( ) and taskSwitchHookDelete( ) 
- Add and delete routines to be called when a task is switched. 


taskDeleteHookAdd( ) and taskDeleteHookDelete( ) 
- Add and delete routines to be called when a task is deleted. 
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This facility is used by dbgLib to provide task-specific breakpoints and 
single-steoping. It is used by taskVarLib for the “task variable’ mechanism. 
It is also used by fppLib for floating-point coprocessor support. 


NOTE 

It is possible to have dependencies among task hook routines. For example, 
a delete hook may use facilities that are cleaned up and deleted by another 
delete hook. In such cases, the order in which the hooks run is important. 
Vx960 runs the create and switch hooks in the order in which they were 
added, and runs the delete hooks in reverse of the order in which they were 
added. Thus, if the hooks are added in “hierarchical” order, such that they 
rely only on facilities whose hook routines have already been added, then 
the required facilities will be initialized before any other facilities need them, 
and will be deleted after all facilities are finished with them. 


Vx960 facilities guarantee this by having each facility's initialization routine 
first call any prerequisite facility's initialization routine before adding its 
own hooks. Thus, the hooks are always added in the correct order. Each 
initialization routine protects itself from multiple invocations, allowing only 
the first invocation to have any effect. 


SEE ALSO 
taskLib, Programmer's Guide: Basic OS 
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NAME . | 
taskCreateHookAdd{ ) - add a routine to be called at every task create 


SYNOPSIS 
STATUS taskCreateHookAdd (createHook) 
FUNCPTR createHook; /* routine to be called when a tesk is created */ 


DESCRIPTION 
This routine adds a specified routine to a list of routines that will be called 
whenever a task is created. The routine should be declared as follows: 


VOID createHook (piiewTcb) 
WIND _TCB *pMewlch; /* pointer to new task’s TCB * 


RETURNS 
OK, or ERROR if the table of task create routines is full. 
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SEE ALSO 
taskHookLib, taskCreateHookDelete( ) 
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NAME 
taskCreateHookDelete( ) - delete a previously added task create routine 


SYNOPSIS 
STATUS taskCreateHookDelete (createHook) 
FUNCPTR createHook; /* routine to be deleted from list */ 


DESCRIPTION 
This routine removes a specified routine from the list of routines to be called 


at each task create. 


RETURNS 
OK, or ERROR if the routine is not in the table of task create routines. 


SEE ALSO 
taskHookLib, taskCreateHookAdd( ) 
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NAME 


taskCreateHookShow( )- show the list of. task create FOULNES oie seid 


SYNOPSIS ott ; 
VOID taskCreateliookshow ay ee 


DESCRIPTION 
This routine shows all the task create routines installed: in: ‘the: -task--create 
hook table in the order they were installed. 


RETURNS 
N/A 


SEE ALSO 
taskHookLib, taskCreateHookAdd{ ) 


xe 
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NAME 


taskSwitchHookAdd{ ) - add a routine to be called at every task switch 


SYNOPSIS 
STATUS task#witchHookAdd (switchHook) 
FUNCPTR switchHook; /* routine to be called at every task switch */ 


DESCRIPTION 
This routine adds a specified routine to a list of routines that will be called at 
every task switch. The routine should be declared as follows: 


VOID switchHook (pOldTcb, pitewTcb) 
WIND TCB *pOldTcb; /* pointer to old task’s WIMD_TCS * 
WIND TCB *pHewtcb; /* pointer to new task’s WIMD_TCB * 


RETURNS 
OK, or ERROR if the table of task switch routines is full. 


SEE ALSO | 
taskHookLib, taskSwitchHookDelete( ) 
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NAME | | | : 
taskSwitchHookDelete( ) - delete a previously added task switch routineicicsiy aces 
SYNOPSIS | a . 
. PUSCPER  pwitchHcok; /* routine. to= be deleted: from: list peer ne fom aad asb-ae 
DESCRIPTION _ ' 22 | 
This routine removes the specified’ routine from the list i Toutines.to: be. ::::: 
called at each task switch. 
RETURNS | | : 
OK, or ERROR if the routine is not in the table of task switch routines. :-.- . ae 
SEE ALSO 


taskHookLib, taskSwitchHookAdd( ) 
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NAME 

taskSwitchHookShow ) - show switch routines 
SYNOPSIS 

VOID taskSwitchKookShow () 
DESCRIPTION 


This routine shows all the switch routines installed in the task switch hook 
table in the order they were installed. 


RETURNS 
N/A 


SEE ALSO 
taskHookLib, taskSwitchHookAdd( ) 
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NAME 
taskDeleteHookAdd( ) - add a routine to be called at every task delete 


SYNOPSIS 
STATUS taskDeleteHookAdd (deleteHook) 
FUMCPTR deleteNook; /* routine to be called when a task is deleted */ 


DESCRIPTION | 
This routine adds a specified routine to a list of routines that will be called 
whenever a task is deleted. The routine should be declared as follows: 


VOID deleteHook (pTcb) - 
WIMD_TCB *pTch; /* pointer to deleted task’s WIND_TCB * 


RETURNS 
OK, or ERROR if the table of task delete routines is full. 


SEE ALSO 
taskHookLib, taskDeleteHookDelete( ) 
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NAME 
taskDeleteHookDelete( ) - delete'a previously added task delete routine 


SYNOPSIS 


STATUS taskDeleteHookDelete (deleteook) 
FUNCPTR deleteHook; /* routine to be deleted from list */ 


DESCRIPTION 
This routine removes a specified routine from the list of routines to be called 
at each task delete. 


RETURNS 
OK, or ERROR if the routine is not in the table of task delete routines. 


SEE ALSO 
taskHookLib, taskDeleteHookAdd( ) 


NAME 
taskDeleteHookShow( ) - show the delete routines 


SYNOPSIS 
VOID taskDeleteHockShow () 


DESCRIPTION 
This routine shows all the delete routines installed in the task delete hook 
table in the order they were installed. Note that the delete routines will be 
run in reverse of the order they were installed. 


RETURNS 
N/A 


SEE ALSO 
taskHookLib, taskDeleteHookAdd{ ) 


Rev: 29 Aug 91 Intel 1- 418 


Vx960 5.0 - Reference Manual 


NAME 
taskLib - task management library for the Vx960 kernel 


SYNOPSIS 

taskSpawn( ) - spawn a task 

taskInit( ) - initialize a task with a stack at a specified address 
taskActivate( ) - activate a task that has been initialized 

exit( ) - exit a task 

taskDelete( ) - delete a task 

taskDeleteForce( ) - delete a task without restriction 
taskSuspend() - suspend a task 

taskResume() - resume a task 

taskRestart( ) - restart a task 

taskPrioritySet( ) - change the priority of a task 
taskPriorityGet( ) - examine the priority of a task 

taskLock( ) - disable task rescheduling 

taskUnlock( ) - enable task rescheduling 

taskSafe() - make the calling task safe from deletion 
taskUnsafe( ) - make the calling task unsafe from deletion 
taskDelay( ) - delay a task from executing 

taskOptionsSet{ ) - change task options 

taskOptionsGet{ ) - examine task options 

taskRegsGet( ) - get a task's registers from the TCB 
taskRegsSet( ) - set a task's registers 

taskName( ) - get the name associated with a task ID 
taskNameTold({ ) - look up the task ID associated with a task n name 
tasklIdVerify( ) - verify the existence of a task | | 
taskIdSelf( ) - get the task ID of a running: task ° er 6 
taskIdDefault( ) -‘set the default task ID ' - ee | 
taskIsReady( ) - check ‘if a task is ready torum ono. : 
taskIsSuspended( ) - check if a task is suspended _ 
taskTcb{ ) - get the task contro] block for a task ID: 
taskIdListGet( ) - get alist of active task IDs. 

taskInfoGet{ ) - get information about a task 

taskStatusString( ) - get a task’s status as a string 


int taskSpam (name, priority, options, stackSize, entryPt, ...) 

STATUS taskInit (pycb, name, priority, options, p@tackBase, stackSize, entryPt, . 
STATUS taskActivate (tid) 

VOID exit (code) 

STATUS taskDelete (tid) 
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STATUS taskDeleteForce (tid) 

STATUS taskSuspend (tid) 

STATUS tasknesime (tid) 

STATUS taskRestart (tid) 

STATUS taskPriorityget (tid, newPriority) 
STATUS taskPriorityGet, (tid, pPriority) 
STATUS taskLock () 

STATUS tasklinlock () 

STATUS taskSafe () 

STATUS taskUnsafe () 

STATUS taskDelay (ticks) 

STATUS taskOptionsSet (tid, mask, newOptions) 
STATUS taskOptionsGet (tid, pOptions) 
STAT’S taskRegsGet (tid, pRegs) 

STATUS taskRegsSet (tid, pitegs) 

char “*taskName (tid) 

int taskMNameToId (name) 

STATUS taskIdVerify (tid) 

int taskIdself () 

int taskIdDefault (tid) 

BOOL taskIsReady (tid) 

BOOL taskIsSuspended (tid) 

WIMD_TCB “taskTcb (tid) 

int taskIdListGet (idList, maxTasks) 
STATUS taskInfoGet (tid, pTaskDesc) 
STATUS taskStatusString (tid, p@tring) 


DESCRIPTION 


This library provides the interface: to 5 the Vx960 task management facilities:=2 ~"- 


Task control services are provided by: the Vx960 kernel, which 4 is Be a 
of kernelLib, taskLib, semLib, tickLibj and wdLib. - a 


~— 


TASK CREATION 2 Sas 
Tasks are created with the eeiakciateds routine taskSpawn({ ). Task crea- 
tion consists of the following: allocation of memory for the stack and task 
control block (WIND_TCB), initialization of: the WIND_TCB, and activation 
of the WIND_TCB. Special needs may require the use of the lower-level. 
routines taskInit( ) and taskActivate( ), which are the underlying primitives. 
of taskSpawn( ). 


Tasks in Vx960 execute in the most privileged state of the underlying archi- 
tecture. In a shared address space, processor privilege offers no protection 
advantages and actually hinders performance. 


There is no limit to the number of tasks created in Vx960, as long as suffi- 
cient memory is available to satisfy allocation requirements. 
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The routine sp() is provided in usrLib as a convenient abbreviation for 
spawning tasks. It calls taskSpawn() with default parameters. 


TASK DELETION 
If a task exits its ““main’’ routine, specified during task creation, the kernel 
implicitly calls exit{ ) to delete the task. Tasks can be explicitly deleted with 
the taskDelete() routine. — 


Task deletion must be handled with extreme care, due to the inherent diffi- 
culties of resource reclamation. Deleting a task that owns a critical resource 
can cripple the system, since the resource may no longer be available. Sim- 
ply returning a resource to an available state is not a viable solution, since 
the system can make no assumption as to the state of a particular resource at 
the time a task is deleted. 


The solution to the task deletion problem lies in deletion protection, rather 
than overly complex deletion facilities. Tasks may be protected from unex- 
pected deletion using taskSafe() and taskUnsafe(). While a task is safe 
from deletion, deleters will block until it is safe to proceed. Also, a task can 
protect itself from deletion by taking a mutual-exclusion semaphore created 
with the SEM_DELETE_SAFE option, which enables an implicit taskSafe( ) 
with each semTake(), and a taskUnsafe() with each semGive() (see 
semMLib for more information). Many Vx960 system resources are pro- 
tected in this manner, and application designers may wish to consider this 
facility where dynamic task deletion is a possibility. 


The sigLib facility may also be used to allow a task to execute clean-up code 
before actually expiring. 


TASK CONTROL 
Tasks are manipulated by means of an ID that is returned when a task. is 
created. Vx960 uses the convention that specifying a task ID of NULL ina 
task control function signifies the calling task. 


The following routines control task state: taskResume(), ssitetiuniaiit’ 
taskDelay( ), lect taskPrioritySet{ ) and taskRegsSet( ). 


TASK SCHEDULING 
Vx960 schedules tasks on the basis of priority. Tasks may have priorities 
ranging from 0, the highest priority, to 255, the lowest priority. The priority 
of a task in Vx960 is dynamic, and an existing task’s priority can be changed 
- using taskPrioritySet{ ). 


TASK INFORMATION 
The following routines provide task information: taskInfoGet(), 
taskRegsGet(), taskIdListGet({), taskPriorityGet({), taskStatusString( ), 
taskIsSuspended( ), taskIsReady() and taskTcb{ ). Task information is cru- 
cial as a debugging aid and user-interface convenience during the 
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development cycle of an application. Its chief drawback is that tasks may 
change their state between the time the information is gathered and the time 
it is utilized. Information provided by these routines shouid therefore be 
viewed as a snapshot of the system, and not relied upon unless the task is 
consigned to a known state, such as suspended. 


INCLUDE FILE 
taskLib.h 


SEE ALSO 
taskHookLib, taskVarLib, semLib, kernelLib, 
Programmer's Guide: Basic OS 
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NAME 
taskSpawn() - spawn a task 


SYNOPSIS 


int taskSpawn (name, priority, options, stackSize, entryPt, 
argl, arg2, arg3, arg4, args, arg6, arg?7, arg8, arg9, ar 


char nama} /* name of new task (stored at pStackBase) */ 
int priority; /* priority of new task */ | 
int options;  /* task option word */ 
int stackSize; /* size (bytes) of stack needed plus name */ 
FUNCPTR entryPt; /* entry point of new task */ 
int argl; /* task argument one */ 
int arg2; /* task argument two */ 
int arg3; /* task argument three */ 
int erg;  /* task argument four */ 
int arg5} /* task argument five */ 
int arg6; /* task argument six */ 
int arg]; /* task argument seven */ 
int arg8; /* task argument eight */ 
int arg9}; /* task argument nine */ 
int arglO; /* task argument ten */ 
DESCRIPTION 


This routine creates and activates a new task with a specified priority and 
options and returns a system-assigned ID. See taskInit() and 
taskActivate( ) for the building blocks of this routine. 


A task may be assigned a name as a debugging aid. This name will appear 
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in displays generated by various system information facilities such as i(). 
The name may be of arbitrary length and content, | but the current Vx960 con- 


oomon fe cig: ae —m —— a ase uae ws on Gsgr 
vention is to limit task names to ten characters and a prefix them witha “’t”. If 


name is specified as NULL, an ASCII name will be assigned to the task of the 
form “tr/’ where n is an integer which increments as new tasks are spawned. 


The only resource allocated to a spawned task is a stack of a specified size 
stackSize, which is allocated from the system memory partition. Stack size 
should be an even integer. A task control block (TCB) is carved from the 
stack, as well as any memory required by the task name. The remaining 
memory is the task’s stack and every byte is filled with the value OxEE for 
the checkStack( ) facility. See the manual entry for checkStack{ ) for stack- 
size checking aids. 


The entry address entryPt is the address of the “main” routine of the task. 
The routine will be called once the C environment has been set up. The 
specified routine will be called with the ten given arguments. Should the 
specified main routine return, a call to exit{ ) will automatically be made. 


Bits in the options argument may be set to run with the following modes: 
VX_UNBREAKABLE - do not allow breakpoint debugging 


VX_FP_TASK - execute with coprocessor support 
VX_STDIO - execute with standard I/O support 
See the definitions in taskLib.h. 
RETURNS 
The task ID, or ERROR if memory is insufficient or the task cannot be 
created. 
SEE ALSO 


taskLib, taskinit ), taskActivate( ), — Sp), ‘ 
Programmer's Guide: BasicOS *: ° a 


NAME 


taskInit( ) - initialize a task with a stack at a specified address 


SYNOPSIS 
STATUS taskInit (pTcb, name, priority, options, pStackBase, stackSize, entryPt, 


argl, arg2, arg3, arg4, arg5, arg6, arg], arg’, arg9, 
WIED_TCB ‘*pTcb; /* address of new task’s TCB */ 
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char *name} /* name of new task (stored at pStackBase) */ 

int priority; /* priority of new task */ 

int ootions; /* task option word */ 

char *pStackBase; /* bottom of new task’s stack */ 

int stackSize; /* size (bytes) of stack needed */ 

FUNCPTR entryPt; /* entry point of new task */ 

int argl; /* task argument one */ 

int arg2; /* task argument two */ 

int arg3} /* task argument three */ 

int  argé; /* task argument four */ 

int arg5; /* task argument five */ 

int arg6; /* task argument six */ 

int arg7; /* task argument seven */ 

int arg8} /* task argument eight */ 

int arg9; /* task argument nine */ 

int arglO; /* task argument ten */ 
DESCRIPTION 


This routine initializes user-specified regions of memory for a task stack and 
control block instead of allocating them from memory as taskSpawn() does. 
This routine will utilize the specified pointers to the WIND_TCB and stack 
as the components of the task. This allows, for example, the initialization of 
a static WIND_TCB variable. It also allows for special stack positioning as a 
debugging aid. 


As in taskSpawn() a task may be given a name. While taskSpawn() 
automatically names unnamed tasks, taskInit() permits the existence of 
tasks without names. 


Other arguments are the ‘same as in -taskSpawn(). Unlike taskSpawn(), 
taskInit{) does not activate the- -fask. - pats must aaa done 2 — 
taskActivate( ) after calling taskInit()é: 


Normally, tasks should be statted: vasing * taskSdaunt) | ‘rathér-‘than. 
taskInit( ), except when additional‘cortrok is required: fortask« oeeey. -allo--- 


cation or a i gia task activation is desired. 


RETURNS 
OK, or ERROR if the task cannot be initialized. 


SEE ALSO © 
taskLib, taskActivate( ), taskSpawn() 
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NAME 
taskActivate( ) - activate a task that has been initialized 


SYNOPSIS 
STATUS taskActivate (tid) 
int tid; /* task ID of task to activate */ 


DESCRIPTION } 
This routine activates tasks created by taskInit( ). Without activation, a task 
is ineligible for CPU allocation by the scheduler. 


The taskSpawn( ) routine is built from taskActivate( ) and taskInit( ). Tasks 
created by taskSpawn( ) do not require explicit task activation. 


RETURNS 
OK, or ERROR if the task cannot be activated. 


SEE ALSO 
taskLib, taskInit( ) 
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NAME 


SYNOPSIS 
VOID exit (code) 
int code; /* code stored in TCS for delete hooks */ 


DESCRIPTION 
A task may call this routine to cease to exist as a task. It is called implicitly 
when the “main” routine of a spawned task is exited. The code parameter 
will be stored in the WIND_TCB for possible use by the delete hooks, or 
post-mortem debugging. 


SEE ALSO | 
taskLib, taskDelete( ), Programmer's Guide: Basic OS 


exit() - exit a task 
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NAME 
taskDelete( ) - delete a task 


SYNOPSIS | 
«STATUS taskDelete (tid) 
int tid; /* task ID of task to delete */ 


DESCRIPTION 
This routine causes a specified task to cease to exist and deallocates the 
stack and WIND_TCB memory resources. Upon deletion, all routines speci- 
fied by taskDeleteHookAdd() will be called in the context of the deleting 
task. This routine is the companion routine to taskSpawn( ). 


RETURNS 
OK, or ERROR if the task cannot be deleted. 


SEE ALSO 
taskLib, excLib, taskDeleteHookAdd( ), taskDelete( ), 
Programmer's Guide: Basic OS 
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NAME 
taskDeleteForce( ) - delete a task without restriction 


SYNOPSIS 
STATUS taskDeleteForce (tid) 
int tid; /* task ID of task to delete */ 


DESCRIPTION 
This routine is equivalent to taskDelete(), except that it deletes a task even 
if the task is protected from deletion. Upon deletion, all routines specified 
by taskDeleteHookAdd{ ) will be called in the context of the deleting task. 


CAVEAT 
This routine is intended as a debugging aid, and is generally inappropriate 
for applications. Disregarding a task’s deletion protection could leave the 
the system in an unstable state. 


RETURNS , 
OK, or ERROR if the task cannot be deleted. 
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SEE ALSO 
taskLib, taskDeleteHookAdd({ ), taskDelete( ) 


NAME 
taskSuspend() - suspend a task 


SYNOPSIS 
STATUS taskSuspend (tid) 
int tid; /* task ID of task to suspend */ 


DESCRIPTION : 
This routine suspends a specified task. A task ID of zero results in the 
suspension of the calling task. Suspension is additive, thus tasks may be 
delayed and suspended, or pended and suspended. Suspended, delayed 
tasks whose delays expire will remain suspended. Likewise, suspended, 
pended tasks that unblock will only remain suspended. 


RETURNS 
OK, or ERROR if the task cannot be suspended. 


SEE ALSO 
taskLib 


NAME ~- A = 


i.  taskResume( )- resume a task | 


SYNOPSIS 
STATUS taskResume (tid) 
int tid; /* task ID of task to resume */ 


DESCRIPTION 
This routine resumes a specified task. Suspension will be cleared, and the 
task will operate in the remaining state. 


RETURNS 
OK, or ERROR if the task cannot be resumed. 
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NAME 
taskRestart( ) - restart a task 


SYNOPSIS 
STATUS taskRestart (tid) 
int tid; /* task ID of task to restart */ 


DESCRIPTION 
This routine “restarts” a task. The task is first terminated, and then reinitial- 
ized with the same ID, priority, options, original entry point, stack size, and 
parameters it had when it was terminated. Self-restarting of a calling task is 
performed by the ia di irae The shell utilizes this routine to restart 


itself when aborted: - 
NOTE 
If the task has modified any-of.its:start-up parameters, the restarted task will 
start with the changed values. 
RETURNS | 
OK, or ERROR if the task ID is invaues or the task could not be restarted. 
SEE ALSO 
taskLib 
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NAME 
taskPrioritySet{ ) - change the-priority of a task 


SYNOPSIS 
STATUS taskPrioritySet (tid, newPriority) 
int tid; /* task ID */ 
int newPriority; /* new priority */ 
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DESCRIPTION 
This routine changes a task’s priority to a specified priority. Priorities range 
from 0, the highest priority, to 255, the lowest priority. 


RETURNS 
OK, or ERROR if the task ID is invalid. 


SEE ALSO 
taskLib, taskPriorityGet{ ) 


NAME 
taskPriorityGet{ ) - examine the priority of a task 


SYNOPSIS 
STATUS taskPriorityGet (tid, pPriority) 
int tid; /* task ID */ 
int ‘*pPriority; /* return priority here */ 


DESCRIPTION 
This routine determines the current priority of a specified task. The current 
priority is copied to the integer pointed to by pPriority. 


RETURNS 
OK, or ERROR if the task ID is invalid. 


SEE ALSO 
taskLib, taskPrioritySet( ) 
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NAME : 
taskLock( ) - disable task rescheduling 


SYNOPSIS 
STATUS taskLock () 


DESCRIPTION | 
This routine disables task context switching.‘ The task that calls this routine 
will be the only task that is allowed to execute, unless the task explicitly 
gives up the CPU by making itself no longer ready. Typically this call is 
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paired with taskUnlock( ); together they surround a critical section of code. 
These preemption locks are implemented with a counting variable that 
allows nested preemption locks. Preemption will not be unlocked until 
taskUnlock( ) has been called as many times as taskLock{( ). 


This routine does not lock out interrupts; use intLock() to lock out inter- 
rupts. 


A taskLock() is preferable to intLock() as a means of mutual exclusion, 
because interrupt lock-outs add interrupt latency to the system. 


A semTake() is preferable to taskLock() as a means of mutual exclusion, 
because preemption lock-outs add preemptive latency to the system. 


RETURNS 
OK or ERROR. 


SEE ALSO 
taskLib, taskUnlock( ), intLock( ), taskSafe(), semTake( ) 


NAME 
taskUnlock( ye enable task rescheduling 


SYNOPSIS 
STATUS taskUnlock () 


DESCRIPTION 
This routine decrements the preemption lock count. Typically this call is 
paired with taskLock{ ) and concludes a critical section of code. Preemption 
will not be unlocked until taskUnlock() has been called as many times as 
taskLock(). When the lock count is decremented to zero, any tasks that 
were eligible to preempt the current task will execute. 


RETURNS 
OK or ERROR. 


SEE ALSO 
taskLib, taskLock( ) 
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NAME 

taskSafe() - make the calling task safe from deletion 
SYNOPSIS 

STATUS taskSafe () 
DESCRIPTION 


This routine protects the calling task from deletion. Tasks that attempt to 
delete a protected task will block until the task is made unsafe, using 
taskUnsafe(). When a task becomes unsafe, the deleter will be unblocked 
and allowed to delete the task. 


The taskSafe() primitive utilizes a count to keep track of nested calls for 
task protection. When nesting nesting occurs, the task becomes unsafe only 
after the outermost taskUnsafe( ) is executed. 


RETURNS 
OK 


SEE ALSO 
taskLib, Programmer's Guide: Basic OS 
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NAME 
taskUnsafe( ) - make the calling task unsafe from: deletion 
SYNOPSIS SEM eS er > & 
" graTus taskUnsafe ()Es054 tasipenty py eb fat we orks 
: DESCRIPTION 


This routine removes the ‘elie task’s protectiori:feonr deletion. ‘Tasks that ~~- 


attempt to delete a protected task will block until! the task is urisafe: When‘a- 
task becomes unsafe, the deleter will bé unblocked: and’ ‘allowed to delete the ‘ 
task. 


The taskUnsafe( ) primitive utilizes a count to keep track-of nésted. calls for 
task protection. When nesting occurs, the task becomes unsafe only after 
the outermost taskUnsafe( ) is executed. 
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RETURNS 
OK 


SEE ALSO 
taskLib, Programmer's Guide: Basic OS 


VIET ERS 
RS & 


ERE. 
Bess 


NAME 
taskDelay( ) - delay a task from executing 


SYNOPSIS 
STATUS taskDelay (ticks) 
int ticks; /* number of ticks to delay task */ 


DESCRIPTION 
This routine causes the calling task to relinquish the CPU for the duration 
specified (in ticks). This is commonly referred.to as manual rescheduling, 
but it is also useful when waiting for some external condition that does not 
have an interrupt associated with it. | 


RETURNS 
OK, or ERROR if called from interrupt level. 
SEE ALSO 
taskLib 
eeresarememmencuynaueucse te yg 
ENDER ROMS ORE ELE EEE ; EL ELE MM 


NAME 
taskOptionsSet{ ) - change task options sh eee Ee ke ke 
SYNOPSIS 
STATUS taskOptionssget (tid, mask, newOptions) ge oR ag 
int tid; /* task ID */ | 
int mask; /* mask, 1 = ok to change this bit */ 
int newOptions; /* new options */ 
DESCRIPTION 


This routine changes the execution options of a task. The only options that 
are alterable after task creation are the following: 
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VX_UNBREAKABLE - do not allow debugging 
See the definitions in traskLib.h. 


RETURNS 
OK, or ERROR if the task ID is invalid. 


SEE ALSO | 
taskLib, taskOptionsGet{ ) 


NAME 
taskOptionsGet{ ) - examine task options 


SYNOPSIS 
STATUS taskOptionsGet (tid, pOptions) 
int tid; /* task ID */ 
int ‘*pOptions; /* task’s options */ 


DESCRIPTION 
This routine gets the current execution options of the specified task. Bits in 
the options argument may be set to indicate the following modes: 


VX_UNBREAKABLE - do not allow debugging 


VX_FP_TASK - execute with coprocessor support 
VX_STDIO - execute with standard I/O support 
| See the definitions in taskLib.h. | 
RETURNS 
OK, or ERROR if the task ID is invalid. 
335 SEE ALSO 
taskLib, taskOptionsSet{( ) 
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NAME 
taskRegsGet( ) - get a task’s registers from the TCB 


SYNOPSIS 
STATUS taskRegsGet (tid, pRegs) 
int tid; /* task ID */ 
REG SET ‘*pRegs; /* put register contents here */ 


DESCRIPTION 
This routine gathers task information kept in the TCB. It copies the contents 


of the task’s registers to the register structure pRegs. 


NOTE 
This routine only works well if the task is known to be in a stable, not- 
running state. Self-examination, for instance, is ill advised, as results are 


unpredictable. 


RETURNS 
OK, or ERROR if the task ID is invalid. 


SEE ALSO 
taskLib, taskSuspend( ), taskRegsSet( ) 


NAME 
taskRegsSet( ) - set a task’s registers 


SYNOPSIS 
STATUS taskRegsSet (tid, pRegs) 
int tid;  /* task ID */ 
REG SET ‘*pRegs; /* get register contents from here */ 


DESCRIPTION 
This routine loads a specified register set pRegs into a specified task’s TCB. 


NOTE 
This routine only works well if the task is known not to be in the ready state. 
Suspending the task before changing the register set is recommended. 
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RETURNS 
OK, or ERROR if the task ID is invalid. 


NAME 
taskName( ) - get the name associated with a task ID 


SYNOPSIS 
char *taskMame (tid) 
int tid; /* ID of task whose name is to be found */ 


DESCRIPTION | 
This routine returns a pointer to the name of a task of specified ID, if it has a 
name; otherwise it returns NULL. 


RETURNS 
A pointer to the task name, or NULL if the task ID is invalid. 


SEE ALSO 
taskLib 
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NAME eas 
taskNameTold( ) - look up the task.ID associated with a'task narne: - 


SYNOPSIS 
int taskMemeToId (name) i 
char ‘name; /* Ocak Wiad alos ape) . oF 


~ 
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DESCRIPTION 
This routine returns the ID of the task matching a specified name. Referenc-. 
ing a task in this way is inefficient, since it involves a search of the task list. 


RETURNS 
The task ID, or ERROR if the task is not found. 
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SEE ALSO 
taskLib 
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NAME 
taskIdVerify( ) - verify the existence of a task 


SYNOPSIS 
STATUS taskIdVerify (tid) 
int tid; /* task ID */ 


DESCRIPTION 
This routine verifies the existence of a specified task by validating the speci- 
fied ID as a task ID. 


RETURNS 
OK, or ERROR if the task ID is invalid. 


SEE ALSO 
taskLib, objVerify( ) 
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NAME 
taskIdSelf() - get the task ID ofarunningtask —= © ED hes 


SYNOPSIS 
int taskIdfelf () 


DESCRIPTION 
This routine gets the task ID of the.calling task.. The:task ID. will be-invalid if 2. :-- 
called at interrupt level. | 


RETURNS 
The task ID of the calling task. 


SEE ALSO 
taskLib 
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NAME 
taskIdDefault( ) - set the default task ID 


SYNOPSIS 
int taskIdDefault (tid) 
int tid; /* user supplied task ID; if 0, return default */ 


DESCRIPTION 
This routine maintains a global default task ID. This ID is used by libraries 
that want to allow a task ID argument to take on a default value if the user 
did not explicitly supply one. 


If tid is not zero (i.e., the user did specify a task ID), the default ID is set to 
that value, and that value is returned. If tid is zero {(i.e., the user did not 
specify a task ID), the default ID is not changed and its value is returned. 
Thus the value returned is always the last task ID the user specified. 


RETURNS 
Most recent non-zero task ID. 


SEE ALSO 
taskLib, dbgLib, Programmer's Guide: Debugging 


NAME | 
taskIsReady( ) - check if a task is ready to run 


SYNOPSIS 
BOOL taskIsReady (tid) 
imt tid; /* task ID */ 


DESCRIPTION 
This routine tests the status field of a task to determine if it is ready to run. 


RETURNS 
TRUE if the task is ready, otherwise FALSE. 


SEE ALSO 
taskLib 
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NAME 
taskIsSuspended( ) - check if a task is suspended 


SYNOPSIS 
BOOK, taskIsSuspended (tid) 
int tid; /* task ID */ 


DESCRIPTION 
This routine tests the status field of a task to determine if it is suspended. 


RETURNS 
TRUE if the task is suspended, otherwise FALSE. 


NAME 
taskTcb( ) - get the task control block for a task ID 


SYNOPSIS 
WIMD TCB *taskTcb (tid) 
int tid; /* task ID */ 


DESCRIPTION | 
This routine returns a pointer to the task control block (TCB) for a specified 


task. Although all task state information is contained in the TCB, users must 
not modify it directly. To change registers, for instance, use taskRegsSet( ) 
and taskRegsGet( ). 


RETURNS 
A pointer to a WIND_TCB, or NULL if the task ID is invalid. 


SEE ALSO 
taskLib 
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NAME 
taskIdListGet( ) - get a list of active task IDs 


SYNOPSIS 
int taskIdListGet (idList, maxTasks) 
int idiist{]; /* array of task IDs to be filled in */ 
int maxTasks; /* max tasks <idList> can accommodate */ 


DESCRIPTION | 
This routine provides the calling task with a list of all active tasks. An 


unsorted list of task IDs for no more than maxTasks tasks is put into idList. 


WARNING | | 
Kernel rescheduling is disabled with taskLock() while tasks are filled into 
the idList. There is no guarantee that all the tasks are valid or that no new 
tasks have been created by the time this routine returns. 


RETURNS | 
The number of tasks put into the ID list. 


SEE ALSO 
taskLib 
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NAME : 
_taskInfoGet{( ) - get information about a task 


SYNOPSIS i aa 
STATUS taskInfoGet (tid, pTaskDesc) ; 
int tid; /* ID of task for which to get info */ 
TASK DESC ‘*pTaskDesc; /* task descriptor to be filled in */ 


DESCRIPTION 
This routine fills in a specified task descriptor (TASK_DESC) for a specified 
task. The information in the task descriptor is, for the most part, a copy of 
information kept in the WIND_TCB. The TASK_DESC is useful for com- 
mon information and avoids dealing directly with the unwieldy 
WIND_TCB. 
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NOTE 
Examination of WIND_TCBs should be restricted to debugging aids. 


RETURNS 
OK, or ERROR if the task ID is invalid. 


NAME 
taskStatusString{ ) - get a tasks status as a string 


SYNOPSIS 
STATUS taskStatusString (tid, pétring) 
int tid; /* task to get string for */ 
char ‘“pString; /* where to return string */ 


DESCRIPTION 


Fora specified task, this routine deciphers the WIND task status word in the:=* 


TCB and copies the appropriate string to pString. 
EXAMPLE 


-> taskStatusString (taskMNameToId ("shell"), xx=malloc (10)); ay Ge deatesaee 


. new symbol “xx" added to symbol table. 
value = 0 = 0x0 | 

-> printf (“shell status = <ts>\n",; xx). . 
shell status = <READY> | 
value = 2 = 0x2 ete 


RETURNS 
OK, or ERROR if the task IDi is invalid. 


SEE ALSO 
taskLib 
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NAME 


taskVarLib - task variables support library 


SYNOPSIS 
taskVarInit( ) - initialize the task variables facility 
taskVarAdd( ) - add a task variable to a task 
taskVarDelete( ) - remove a task variable from a task 
taskVarGet{ ) - get the value of a task variable 
taskVarSet{ ) - set the value of a task variable 
taskVarInfo{ ) - get a list of task variables of a task 


STATUS taskVariInit () 

STATUS taskVarAdd (tid, pVar) 

STATUS taskVarDelete (tid, pVar) 

int taskVarGet (tid, pVar) 

STATUS taskVarset (tid, pvar, value) 
int taskVariInfo (tid, varList, maxVars) 


DESCRIPTION , 
Vx960 provides a facility called “task variables,’ which allows 4-byte vari- 
ables to be added to a task’s context, and the variables’ values to be switched 
each time a task switch occurs to or from the calling task. Typically, several 
tasks declare the same variable (4-byte memory location) as a task variable 
and treat that memory location as their own private variable. For example, 
this facility can be used when a routine must be spawned more than once as 
several simultaneous tasks. 


The routines taskVarAdd() and taskVarDelete( ) are used to add or delete a 
task variable. The routines taskVarGet( ).and taskVarSet( ) are used to get 
or set the value of a task variable. 


NOTE | 
If you are using task variables in a task delete hook (see taskHookLib), refer 
to the manual entry for taskVarInit{ ) for warnings on proper usage. 


SEE ALSO | 
taskHookLib, Programmer's Guide: Basic OS 
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NAME 
taskVarInit( ) - initialize the task variables facility 


SYNOPSIS 
STATUS taskVarInit () 


DESCRIPTION 
This routine initializes the task variables facility. It installs task switch and 
delete hooks used for implementing task variables. If taskVarInit( ) is not 
called explicitly, taskVarAdd{( ) will call it automatically when the first task 
variable is added. 


After the first invocation of this routine, subsequent invocations have no 
effect. 


WARNING 
Order dependencies in task delete hooks often involve task variables. If a 
facility uses task variables and has a task delete hook that expects to use 
those task variables, the facility's delete hook must run before the task vari- 
ables’ delete hook. Otherwise, the task variables will be deleted by the time 
the facility's delete hook runs. 


Vx960 is careful to run the delete hooks in reverse of the order in which they 
were installed. Any facility that has a delete hook that will use task vari- 
ables can guarantee proper ordering by calling taskVarInit( ) before adding 
its own delete hook. 


Note that this is not an issue in normal use of task variables. The issue only 
arises when adding another task delete hook that uses task variables. 


RETURNS 
OK, or ERROR if the task switch/delete hooks could not be installed. 


SEE ALSO 
taskVarLib 
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NAME 


taskVarAdd( ) - add a task variable to a task 


SYNOPSIS 
STATUS taskVarAdd (tid, pVar) 
int tid; /* YD of task to have new variable */ 
int ‘*pvar; /* pointer to variable to be switched for task */ 


DESCRIPTION 


This routine adds a specified variable pVar (4-byte memory location) to a 
specified task’s context. After calling this routine, the variable will be 
private to the task. The task can access and modify the variable, but the 
modifications will not appear to other tasks, and other tasks’ modifications 
to that variable will not affect the value seen by the task. This is accom- 
plished by saving and restoring the variable’s initial value each time a task 
switch occurs to or from the calling task. 


This facility can be used: when a routine is to be spawned repeatedly as 
several independent tasks. Although each task will have its own stack, and 
thus separate stack variables, they will all share the same static and global 
variables. To make a variable mot shareable, the routine can call 
taskVarAdd() to make a separate copy of the variable for each task, but all 
at the same physical address. 


Note that task variables increase the task switch time to and from the tasks 
that own them. Therefore, it is desirable to limit the number. of task vari- 
ables that a task uses: =An‘efficient use of task variables is to havea single ~ 
task variable that isa a toa ecratiaeae | allocated structure containing 
the task’s — data.” >": 


EXAMPLE  -s-S#A.2" 
_ Assume that + thas identical tasks :were iepauiaied with a routine.called opera- 
tor (). They use thé-stécture,OPR-GLOBAL for:all variables ‘that are specific 
to a particular incarnatjorv‘of: the task. The following code fragment shows 
how this is set up: : | 


OP_ GLOBAL *opGlobal; /* pointer to operator task’s global variables * 


Operator (op um) 
int opium; /* number of this operator task * 


{ 
if (taskVarAdd (0, (int *)&opGlobal) != OK) 
{ | | 
printErr (“operatortd: can’t taskVarAdd opGlobal\n", opitum); 
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taskSuspend (0); 
} 


if ((opGlobal = (OP GLOBAL *) malloc (sizeof (0% GLOBAL))) == NULL) 


{ 
printErr ("operatortd: can’t malloc opGlobal\n", opium); 
taskSuspend (0); 


} 
} 
RETURNS 
OK, or ERROR if memory is insufficient for the task variable descriptor. 
SEE ALSO 


taskVarLib, taskVarDelete( ), taskVarGet( ), taskVarSet( ) 


NAME 
taskVarDelete( ) - remove a task variable from a task 


SYNOPSIS 
STATUS taskVarDelete (tid, pVar) 
int tid; /* ID of task whose variable is to be removed */ 
int ‘*pvar; /* pointer to task variable to be removed */ 


DESCRIPTION . | 
This routine removes a specified task variable (pVar) from the specified 


task’s context. The private value of that variable is lost. 


RETURNS 
OK, or ERROR if the task variable does not exist for the specified task. 


SEE ALSO : 
taskVarLib, taskVarAdd( ), taskVarGet( ), taskVarSet{ ) 


Rev: 29 Aug 91 intel 1- 441 


Vx960 5.0 - Reference Manual 


NAME 
taskVarGet( ) - get the value of a task variable 


SYNOPSIS 
int taskvarGet (tid, pVar) 
int tid; /* ID of task whose task variable is to be retrieved */ 
int ‘*pVar; /* pointer to task variable */ 


DESCRIPTION 
This routine returns the private value of a task variable for a specified task. 
The specified task is usually not the calling task, which can get its private 
value by directly accessing the variable. This routine is provided primarily 
for debugging purposes. 


RETURNS 
The private value of the task variable, or ERROR if the task is not found or it 
does not own the task variable. 


SEE ALSO 
taskVarLib, taskVarAdd{ ), taskVarDelete( ), taskVarSet( ) 


NAME | 
taskVarSet{ ) - set the value of a task variable 


SYNOPSIS 
STATUS taskVarSet (tid: pYar, value) —-- eee 
int tid; /* ID of task whose task variable {ts to beset */: 
int ‘*pVar; /* pointer to task variable to be set for this task oo 
int value; /* new. value of task variable */ | 


DESCRIPTION | 
This routine sets the peivate value of the task variable for a specified task. 
The specified task is usually not the calling task, which can set its private 
value by directly modifying the variable. This routine is provided primarily 
for debugging purposes. 


RETURNS 
OK, or ERROR if the task is not found or it does not own the task variable. 
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NAME 
taskVarinfot{ ) - get a list of task variables of a task 
SYNOPSIS 
int taskVarInfo (tid, varList, maxVars) 
int tid; /* ID of task whose task variable is to be set */ 
TASK VAR varList[}; /* array of task variable addresses to be filled in */ 
int maxVars} /* maximm variables varList can accommodate */ | 
DESCRIPTION 


This routine provides the calling task with a list of all of the task variables.of . 
a specified task. The unsorted array of task variables is copied to varList. ... . 


CAVEATS 
Kernel rescheduling is disabled with taskLock() while task variables are _ . 
looked up. There is no guarantee that all the task variables are-stilk validsor=*:*::2 2: 
that no new task variables have been created by the time this routine | 
retums. 


RETURNS 
The number of tasks variables in the list. 


SEE ALSO 
taskVarLib 
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NAME 
telnetLib - telnet library 


SYNOPSIS oe 
telnetInit( ) - initialize the telnet daemon 
telnetd() - Vx960 telnet daemon 


VOID telnetInit () 
VOID telnetd () 


DESCRIPTION 
This library provides a remote login facility for Vx960. It uses the ARPA tel- 
net protocol to enable users on remote systems to log into Vx960. 


The telnet daemon, telnetd(), accepts remote telnet login requests and 
causes the shell’s input and output to be redirected to the remote user. The 
telnet daemon is started by calling telnetInit(); if INCLUDE_TELNET is 
defined in configAll.h, it is called from the root task, usrRoot(), in 
usrConfig.c. 


Internally, the telnet daemon provides a tty-like interface to the remote user 
through the use of the Vx960 pseudo-terminal driver, ptyDrv. 


SEE ALSO 
ptyDrv, rlogLib, UNIX documentation for telnet, telnetd, and pty 


NAME 
telnetInit( ) - initialize the telnet daemon 


SYNOPSIS 
VOID telnetInit () 


DESCRIPTION 
This routine initializes the telnet facility, which supports remote login to the 
Vx960 shell via the ARPA telnet protocol. It creates a pty device and spawns 
the telnet daemon. If INCLUDE_TELNET is defined in configAILh, it is 
called from the root task, usrRoot( ), in usrConfig.c, before any system tries 
to log into this Vx960 system via telnet. 
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RETURNS 
N/A 


SEE ALSO 
telnetLib 
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NAME 


telnetd() - Vx960 telnet daemon 


SYNOPSIS 
VOID telnetd () 


DESCRIPTION 
This routine enables remote users to log into Vx960 over the network via the 
ARPA telnet protocol. It is spawned by telnetInit( ), which should be called 
by usrRoot() at boot time. 


Remote telnet requests will cause stdin, stdout, and stderr to be stolen away 
from the console. When the remote user disconnects, stdin, stdout, and stderr 
are restored, and the shell is restarted. 


The telnet daemon requires the existence of a pseudo-terminal device, which 
is created by telnetInit( ) before telnetd() is spawned. The telnetd() routine 
creates two additional processes, telnetInTask and telnetOutTask, whenever a 
remote user is logged in. These processes exit when the remote connection 
is terminated. 


RETURNS 
N/A 


SEE ALSO 
telnetLib 
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NAME 
tickLib - clock tick support library 


SYNOPSIS | 
tickAnnounce( ) - announce a clock tick to the kernel 
tickSet() - set the value of the kernel’s tick counter 
tickGet( ) - get the value of the kernel’s tick counter 


VOID tickAnnounce () 
VOID tickSet (ticks) 
ULONG tickGet () 


DESCRIPTION 
This library is the interface to the Vx960 kernel routines that announce a 
clock tick to the kernel, that get the current time in ticks, and that set the 
current time in ticks. 


Kernel facilities that rely.on clock ticks include taskDelay(), wdStart(), 
kernelTimeslice(), and.semaphore timeouts. In each case, the specified 
timeout is relative to the current time, also referred to as “time to fire.” 
Relative timeouts are-not affected by calls to tickSet(), which only changes 
absolute time. The routines tickSet() and tickGet() keep track of absolute 
time in isolation from the rest of the kernel. 


Time-of-day clocks or other auxiliary time bases are preferable for lengthy 
- timeouts of days or more.::The accuracy of such time bases is greater, and 
some external time bases‘éven calibrate themselves from time to time. 


SEE Aiso 
kernelLib, taskLib, sembab; wdLib,: Programmer’ 's Guide Basic OS 
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NAME | 
tickAnnounce( ) - announce.a clock tick to the kernel 


SYNOPSIS 
VOID tickAnnounce () 
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DESCRIPTION 
This routine informs the kernel of the passing of time. It should be called 
from an interrupt service routine that is connected to the system clock. The 
most common frequencies are 60Hz or 100Hz. Frequencies in excess of 
600Hz are an inefficient use of processor power because the system will 
spend most of its time advancing the clock. By default, ns in 
usrConfig calls this routine. | 


RETURNS 
N/A 


SEE ALSO 
tickLib, kernelLib, taskLib, semLib, wdLib, Programmer's Guide: Basic OS 


NAME 


tickSet( ) - set the value of the kernel’s tick counter” © 


SYNOPSIS 
VOID tickSet (ticks) 
ULONG ticks; /* new time in ticks */ 


DESCRIPTION 
This routine sets the internal tick counter to a specified value in ticks. The 
new count will be reflected by tickGet(),.but. will not. change-any delay 
fields or timeouts selected for any taskss For:exampie, if a task is delayed for 
ten ticks, and this routine is called to advance_time, ‘the. sae heed a Mey still | 
be delayed until ten salaieee et erm have been’ made. | 


RETURNS 3 we Bee Fees 
N/A 


SEE ALSO 
tickLib, tickGet( ), tickAnnounce( ):’-°-- 
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NAME 
tickGet( ) - get the value of the kernel’s tick counter 


SYNOPSIS 
ULONG tickGet () 


DESCRIPTION 
This routine returns the current value of the tick counter. This value is set to 
zero at startup, incremented by tickAnnounce(), and can be changed using 
tickSet( ). 


RETURNS 
The most recent tickSet( ) value plus the number of tickAnnounce() calls 
since. 


SEE ALSO 
tickLib, tickSet( ), tickAnnounce( ) 
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NAME 
timexLib - execution timer facilities 


SYNOPSIS 
timexInit( ) - include the execution timer library 
timexClear( ) - clear the list of function calls to be timed 
timexFunc( ) - specify functions to be timed 
timexHelp( ) - display synopsis of execution timer facilities 
timex() - time a single execution of a function or functions | 
timexN( ) - time repeated executions of a function or group of functions 
timexPost( ) - specify functions to be called after timing 
timexPre( ) - specify functions to be called prior to timing 
timexShow( ) - display the list of function calls to be timed 


VOID timexInit () 

VOID timexClear () 

VOID timexFunc (i, func, argl, arg2, arg3, arg4, arg5, arg6, arg], arg3) 
VOID timexHelp () 

VOID timex (func, argl, arg2, arg3, argé, arg5, arg6, arg7, arg8) 

VOID timexN (func, argl, arg2, arg3, arg4, arg5, arg6, arg7, arg8) 

VOID timexPost (i, func, argl, arg2, arg3, arg4, arg5, arg6, arg7, arg8) 
VOID timexPre (i, func, argl, arg2, arg3, arg4, arg5, arg6, arg7, arg8) 
VOID timexShow () 


DESCRIPTION 7 
This library contains routines for timing the execution of programs, indivi- 
dual functions, and groups of functions. The Vx960 system clock is used as 
a time base. Functions that have a short execution time relative to this time 
base can be called repeatedly to establish an average execution time with an 
acceptable percentage of error. 


Up to four functions can be specified to be timed as a group. Additionally, 
sets of up to four functions can be specified as pre- or post-timing functions, 
to be executed before and after the timed functions. The routines 
timexPre() and timexPost() are used to specify the pre- and post-timing 
functions, while timexFunc( ) specifies the functions to be timed. 


The routine timex() is used to time a single execution of a functions or 
group of functions. If called with no arguments, timex() uses the functions 
in the lists created by calls to timexPre( ), timexPost(), and timexFunc(). If 
called with arguments, timex() times the function specified, instead of the 
previous list. The routine timexN() works in the same manner as timex( ) 
except that it iterates the function calls to be timed. 
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EXAMPLES 


NOTE 


The routine timex() can be used to obtain the execution time st a single rou- 
tine: 
= timex myFunc, myArgl, myArg2 , eee 


The routine timexN() calls a function is eat de until a 2% or better toler- 
ance is obtained: 


-> timex myFunc, myArgl, myArg2, eve 


The routines timexPre( ), timexPost({ ), and timexFunc() are used to specify a 
list of functions to be executed as a group: 


-> timexPre 0, myPreFuncl, preArgl, preArg2, ... 
~> timexPre 1, myPreFunc2, preArgl, preArg2, ... 


-> timexFunc 0, myFuncl, myArgl, myArg2, ... 
-> timexFunc 1, myFunc2, myArgl, myArg2, ... 
-> timexFunc 2, myFunc3, myArgl, myArg2, coe 


-> timexPost 0, myPostFunc, postArgl, postArg2, ... 


The list is executed by calling timex( ) or timexN() without arguments: 


—> timex 
or 
. -> timex 


In this example, myPreFuncl and myPreFunc2 are called with their respective 
arguments. myFuncl, myFunc2, and myFunc3 are then called in sequence and 
timed. If timexN() was used, the sequence is called repeatedly until a 2% or 
better error tolerance is achieved. Finally, myPostFunc is called with its argu- 
ments. The timing results are reported after all post-timing functions are 
called. — ) | 


The timings measure the execution time of the routine body, without the 
usual subroutine entry and exit code (usually LINK, UNLINK, and RTS — 


instructions). Also, the time required to set up the arguments and call the ~~ 


routines is not included in the reported times. This is because these timing 
routines automatically calibrate themselves by timing the invocation of a 
null routine, and thereafter subtracting that constant overhead. 


SEE ALSO 


spyLib 
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NAME 
timexInit( ) - include the execution timer library 
SYNOPSIS 
VOID timexInit () 
DESCRIPTION | 
This null routine is provided so that timexLib can be linked in. If 
INCLUDE_TIMEX is defined in configAll.h, it is called by the root task, 
usrRoot( ), in usrConfig.c. 
RETURNS 
N/A 
SEE ALSO 
timexLib 


NAME 


timexClear( ) - clear the list of function calls to be timed 


SYNOPSIS 
VOID timexClear () 


DESCRIPTION 
This routine clears the current list of functions to be timed. 


RETURNS 
N/A 


SEE ALSO 
timexLib 


oe 
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NAME 
timexFunc( ) - specify functions to be timed 
SYNOPSIS 
VOID timexFunc (i, func, argl, arg2, arg3, arg4, arg5, arg6, arg7, arg8) 
int i; #=/* function number in list (0..3) «/ 
FUNCPTR func; /* function to be added (MULL if to be deleted) */ 
dat argl; /* first of up to 8 params called with function */ 
int arg2; 
int arg3} 
int arg4; 
int arg5} 
int arg6} 
int arg]; 
int arg8; 
DESCRIPTION 


This routine adds or deletes functions in the list of functions to be timed as a 
group by calls to timex() or timexN(). Up to four functions can be included 
in the list. The argument 1 specifies the function's position in the sequence 
of execution (0, 1, 2, or 3). A function is deleted by specifying its sequence 
number / and null for the function argument func. 


RETURNS 
N/A 

SEE ALSO 
timexLib 
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NAME 
timexHelp() - display synopsis of execution timer facilities 
SYNOPSIS 
VOID timexHelp () 
DESCRIPTION 
This routine displays the following summary of the available execution 
timer functions: 
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timexlelp Print this list. 

timex (func, [args...}}) Time a single execution. 
timex [func,;[aras...}] Time repeated executions. 
timexClear Clear all functions. 


timexFunc i,func,[args...] Add timed function number i (0,1,2,3). 
timexPre i,func,(args...}] Add pre-timing function number i. 
timexPost i,func,[args...}] Add post-timing function number i. 
timexShow Show all functions to be called. 


Motes: 

1) timexN() will repeat calls enough times to get 
timing accuracy to approximately 2%. 

2) A single function can be specified with timex() and timexN(); 
or, miltiple functions can be pre-set with timexFunc(). 

3) Up to 4 functions can be pre-set with timexFunc(), 
timexPre(), and timexPost(), i.e., i in the range 0 - 3. 

4) timexPre() and timexPost() allow locking/unlocking, or 
raising/lowering priority before/after timing. 


RETURNS 
N/A 


SEE ALSO 
timexLib 


NAME 
timex() - time a single execution of a function or functions 
SYNOPSIS 
VOID timex (func, argl, arg2, arg3, argé, arg5, arg6, arg], arg8) 
FUNCPTR func; /* function to time (optional) «/ 
int argl; /* args with which to call function (optional) */ 
int arg2; 
int arg3} 
int arg4; 
iat arg5} 
int arg6} 
int arg]; 
int arg; 
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DESCRIPTION 
This routine times a single execution of a specified function with up to eight 
of the function's arguments. If no function is specified, it times the execu- 
tion of the current list of functions to be timed, which is created using 
timexFunc( ), timexPre(), and timexPost({). If timex() is executed with a 
function argument, the entire current list is replaced with the single sacs 
fied function. 


When execution is complete, timex() displays the execution time. If the exe- 
cution was so fast relative to the clock rate that the time is meaningless 
(error > 50%), a warning message is printed instead. In such cases, use 
timexN( ). 


RETURNS 
N/A 


SEE ALSO 
timexLib, timexFunc( ) 


NAME 
timexN( ) - time repeated executions of a function or group of functions 
SYNOPSIS 
VOID timexN (func, argl, arg2, arg3, arg4, args5, arg6, arg7, arg8) 
FUNCPTR func; /* function to time (optional) */ 
int argl; /* first of up to 8 params to call function with */ 
int arg2} 
int arg3; 3 
int arg4; ; 
int axrg5; 
int arg6; 
int arg7}; 
int arg8; 
DESCRIPTION | 


This routine times the execution of the current list of functions to be timed 
in the same manner as timex( ); however, the list of functions is called a vari- 
able number of times until sufficient resolution is achieved to establish the 
time with an error less than 2%. (Since each iteration of the list may be meas- 
ured to a resolution of +/- 1 clock tick, repetitive timings decrease this error 
to 1/N ticks, where N is the number of repetitions.) 
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NAME 
timexPost( ) - specify functions to be called after timing 
SYNOPSIS 
VOID timexPost (i, func, argl, arg2, arg3, arg4, arg5, arg6, arg7, arg8) 
int i; /* function number in list (0. .3) */ 
FUNCPTR func; /* function to be added (RULL if to be deleted) */ 
int argl; /* first of up to 8 params to call function with */ 
int arg2} 
int arg3; 
int arg4; 
int arg5; 
int. arg6; 
int arg7} 
int arg8; 
DESCRIPTION 


This routine adds or deletes functions:in: the: list-of functions to-be called : 
immediately following the timed functions:!A maximum of race lect lake 
may be included. Up to eight —— may-be-passed to each function? = 7: 


RETURNS ee coe 
N/A Nps 


SEE ALSO 
timexLib 
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NAME 
timexPre( ) - specify functions to be called prior to timing 
SYNOPSIS _ 
VOID timexPre (i, func, argl, arg2, arg3, argt, args, arg6, arg7, arg8) 
int 43 /* function number in list (0. .3) «/ 
FUNCPTR func; /* function to be added (MULL if to be deleted) */ 
int argl; /* first of up to 8 params to call function with */ 
int arg2; 
int arg3} 
int arg4; 
iat arg5} 
int arg6; 
int arg7} 
int args}; 
DESCRIPTION 


This routine adds or deletes functions in the list of functions to be called 
immediately prior to the timed functions. A maximum of four functions 
may be included. Up to eight arguments may be passed to each function. 


RETURNS 
N/A 

SEE ALSO 
timexLib 


NAME 
timexShow( ) - display the list of function calls to be timed 


SYNOPSIS 
VOID timexShow () 


DESCRIPTION 
This routine displays the current list of function calls to be timed. These lists 
are created by calls to timexPre( ), timexFunc( ), and timexPost ). 
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timexLib 
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NAME 
trcLib - stack trace library 


SYNOPSIS 
trcStack( ) - print trace of function calls from stack 
trcArgCntSet( ) - change the number of arguments printed by trcStack( ) 


VOID trcStack (pRegSet, printRtn) 
UINT32 trcArgCntSet (cnt) 


DESCRIPTION 
This module provides a routine, trcStack(), which traces a stack given the 
current frame pointer, stack pointer, and instruction pointer. The resulting 
stack trace lists the nested routine calls and their arguments. 


This module provides the low-level stack trace facility. A higher-level sym- 
bolic stack trace, implemented on OP of this facility, is provided by the rou- 
tine tt( ) in dbgLib. 


SEE ALSO 
“Debugging”, dbgLib, tt() 


NAME | 
trcStack( )- - print nce of function: calls‘from:stack ~ : 
SYNOPSIS . oaeBYNE? are 
_ Vorb trostack  (pRageeeDpeiwektarsc: pgrccices Se 
; REG_SET | *pRegSet 3- /* pointer to task’.s eegiacee set « / 
FUNCPTR © er tace '/* routine to-print single function call */ 
DESCRIPTION feces 


This routine provides: the. Jow-level stack. trace. function... (A higher-level 
symbolic stack trace:built 6n top of this is provided by:the routine ¢é ) in 
dbgLib.) A list of the.nésted routine calls that are on the stack is printed. 
Only the last routine’s parameters are shown since arguments are passed in 
registers, not on the stack with gcc960. 


The stack being traced should be quiescent. Avoid tracing your own stack. 
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PRINT ROUTINE 
In order to allow symbolic or other alternative printout formats, the call to 
this routine includes the “printRtn’” parameter, which is a routine to be 
called at each nesting level to print out the routine name and its arguments. 
This routine should be declared as follows: 


VOID printRtn (callAdrs, rtnAdrs, nargs, args) 
INSTR “callAdrs; /* address from which routine was called * 


int rtnAdrs; /* address of routine called * 
int nargs; /* number of arguments in call * 
int “args; /* pointer to arguments * 


If a NULL printRtn is specified, a default routine will be used which just 
prints out the call address, function address, and arguments as hex values. 


CAVEAT 
In order to do the trace, some assumptions are made. In general, the trace 
will work for all C language routines, and asembly language routines. How- 
ever, routines written in other languages, strange entries into routines, or 
tasks with corrupted stacks, can make the trace very confused. Also, all 
parameters are assumed to be 32-bit quantities, so structures passed as 
parameters will be displayed as some number of integers. 


SEE ALSO 
trcLib, tt(2) 


NAME in Geea es 
trcArgCntSet( ) - change the number‘of-arguments printed by‘trcStack(:} 3382) c0* 
SYNOPSIS —_ 
UINT32 trcArgCntSet (cnt) “2 ae 
UINT32 cnt; /* value to set count to «/ 
DESCRIPTION 


This routine changes the default number of arguments printed out per func- 
tion call. Note that this only affects the last routine found on the stack since 
arguments are not passed on the stack with gcc960. 


RETURNS | 
Previous argument count. 
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NAME 
tyLib - tty driver support library 


SYNOPSIS 
tyDevInit( ) - initialize the tty device descriptor 
tyAbortFuncSet{ ) - set the abort function 
tyAbortSet( ) - change the abort character 
tyBackspaceSet{ ) - change the backspace character 
tyDeleteLineSet( ) - change the line-delete character 
tyEOFSet{ ) - change the end-of-file character 
tyMonitorTrapSet{ ) - change the trap-to-monitor character 
tyloctl( ) - handle device control requests 
tyWrite( ) - do a task-level write for a tty device 
tyRead( ) - do a task-level read for a tty device 
tyITx( ) - interrupt-level output 
tyIRd{ ) - interrupt level input 


STATUS tyDevInit (pTyDev, rdBufSize, wrtBufSize, txStartup) 
VOID tyAbortFuncSet (func) 

VOID tyAbortSet (ch) 

VOID tyBackspaceGet (ch) 

VOID tyDeleteLineSet (ch) 

VOID tyEOFSet (ch) 

VOID tyMonitorTrapset (ch) | 
STATUS tyIoctl (pTyDev, request, arg) 
int tyWrite (pTyDev, buffer, nbytes) 
int tyRead (pTyDev, buffer, maxbytes) 
STATUS tyITx (pTyDev, pChar) 

STATUS tyIRd (pTyDev, inchar) 


DESCRIPTION , 
This library provides routines used to implement drivers for serial devices. 
It provides all necessary device-independent functions of a normal serial 
channel, including: 
- ring buffering of input and output 
- raw mode 
optional line mode with backspace and line-delete functions 
optional processing of X-on/X-off 
optional RETURN/LINEFEED conversion 
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- optional echoing of input characters 
- optional stripping of the parity bit from 8-bit input 
- optional special characters for shell abort and system restart 


Most of the routines in this library are called only by device drivers. Func- 
tions that normally might be called by an application or interactive user are 
the routines to set special characters, ty...Set{ ). 


USE IN SERIAL DEVICE DRIVERS 

Each device that uses tyLib is described by a data structure of type TY_DEV. 
This structure begins with an I/O system device header so that it can be 
added directly to the I/O system's device list. A driver calls tyDevInit{ ) to 
initialize a TY DEV structure for a specific device and then calls 
iosDevAdd{ } to add the device to the I/O system. 


The call to tyDevInit{ ) takes three parameters: the pointer to the TY_DEV 
structure to initialize, the desired size of the read and write ring buffers, and 
the address of a transmitter start-up routine. This routine will be called 
when characters are added for output and the transmitter is idle. 


Thereafter, the driver can call the following routines to perform the usual. 
device functions: 


tyRead() - user read request to get characters that have been input 
tyWrite() - user write request to put characters to be output 
tyIoctl() - userI/O control request 

tyIRd() — - interrupt-level routine to deliver an input character 
tyITx{) — - interrupt-level routine to get the next output character 


Thus, tyRead( ), tyWrite( ), and tyIoctl() are called from the driver's read, 

write, and I/O control. functions. The routines. tyIRd() and’ tyITx() are : 

called from the driver! ee ee response:to receive andstransmitciverm 
interrupts, respectively?" 


_ Examples of using ‘tyLib in a driver can be found in-any of the tyCoDrv 
drivers in the target directories. 


TTY OPTIONS 
Tty devices have a full range of options that affect the behavior of the dev- 
ice. These options are selected by setting bits in the device option word 
using the FIOSETOPTIONS function in the ioctl() routine (see the section 
I/O CONTROL FUNCTIONS). The following is a list of available options. 
The options are defined in the header file ioLib.h. 


OPT_LINE - Selects line mode. A tty device operates in one of two 
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modes: 
raw mode (unbuffered) or line mode. Raw mode is 
_ the default. In raw mode, each byte of input from the 
device is immediately available to readers, and the 
input is not modified except as directed by other 
options below. In line mode, input from the device is 
not available to readers until a NEWLINE character is 
received, and the input may be modified by back- 
space, line-delete, and end-of-file special characters. 


Causes all input characters to be echoed to the output 
of the same channel. This is done simply by putting 
incoming characters in the output ring as well as the 
input ring. If the output ring is full, the echoing is 
lost without affecting the input. 


OPT_ECHO 


OPT_CRMOD C language conventions use the NEWLINE character 

as the line terminator on both input and output. Most 
terminals, however, supply a RETURN character 
when the return key is hit, and require both a 
RETURN and a LINEFEED character to advance the - -- - 
output line. This option enables the appropriate 
translation: NEWLINEs are substituted for input °° ~ 
RETURN characters, and NEWLINEs in'the output -- 
file are automatically turned into a RETURN- | 
LINEFEED sequence. 


Causes the driver to generate and respond to the spe- | 
cial flow control characters “Q and *S in what:is.comi--.:4:-: -. 
monly known as X-on/X-off protocol.: Receipt'of a**S “~. «/ * 
input character will suspend output to that channel. — 
Subsequent receipt of a “Q will resume-the: output: pot 
Also, when the Vx960 input buffer is almost ‘full,a “S’ 7°? 2a 
will be output to signal the other ‘side ‘to ‘stispend> *!z2! 
transmission. When the input buffer is almost ‘empty, = 
a “Q will be output to signal the other side to resume ~ a due 
transmission. 


OPT_TANDEM 


OPT_7 BIT 


Strips the most significant bit from all bytes input .. 
from the device. 


OPT_MON_TRAP - Enables the special monitor trap character, by default 
*X. When this character is received and this option is 
enabled, Vx960 will trap to the ROM resident monitor 
program. Note that this is quite drastic. All normal 
Vx960 functioning is suspended, and the computer 
system is entirely controlled by the monitor. 
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Depending on the particular monitor, it may or may 
not be possible to restart Vx960 from the point of 
interruption. The default monitor trap character can 
be changed by calling tyMonitorTrapSet( ). 

Enables the special shell abort character, by default 
“C. When this character is received and this option is 
enabled, the Vx960 shell is restarted. This is useful for 
freeing a shell stuck in an unfriendly routine, such as 
one caught in an infinite loop or one that has taken an 
unavailable semaphore. For more information see the 
“Shell” chapter of the Programmer's Guide. 


OPT_TERMINAL .- This is not a separate option bit. It is the value of the 
| option word with all the above bits set. 


OPT_RAW - This is not a separate option bit. It is the value of the 
option word with none of the above bits set. 


OPT_ABORT 


1/O CONTROL FUNCTIONS 
The tty devices respond to the following ioctl() functions. The functions 
are defined in the header ioLib.h. | 


FIOGETNAME __ - Gets the file name of the fd and copies it to the buffer 
referenced to by nameBuf. 


status = ioctl (fd, FIOGETNAME, G&nameBuf) ; 


This function is common to all fds for all devices. 


FIOSETOPTIONS, FIOOPTIONS 
- Sets the device option word to the specified argu- 
ment. For example, the call: 


status = ioctl] (fd, FIOOPTIONG, OPT_TERMIMAL) } 
status = ioctl (fd, FIOGETOPTIONS, OPT _TERMIMAL); 


enables all the tty options described above, putting 
the device in a “normal” terminal mode. If the line 
protocol (OPT_LINE) is changed, the input buffer is 
flushed. The various options are described in ioLib.h. 


FIOGETOPTIONS - Returns the current device option word: 
options = ioctl (fd, FIOGETOPTIONS) ; 


FIONREAD - Copies to nBytesUnread the number of bytes available 


to be read in the device's input buffer: 
ss status = joctl (fd, FIOMREAD, &nBytesUnread) ; 
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FIONWRITE 


FIOFLUSH 


FIOWFLUSH 


FIORFLUSH 


FIOCANCEL 


FIOBAUDRATE 


FIOISATTY 


FIOPROTOHOOK - 
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In line mode (OPT_LINE set), the FIONREAD func- 
tion actually returns the number of characters avail- 
able plus the number of tines in the buffer. Thus, if 
five lines of just NEWLINEs were in the input buffer, 
it would return the value 10 (5 characters + 5 lines). 


Copies to nBytes the number of bytes queued to be 
output in the device's output buffer: 


status = joctl (fd, FICOMRITE, &nBytes) ; 


Discards all the bytes currently in both the input and 
the output buffers: 


status = ioctl (fd, FIOFLUSE); 


Discards all the bytes currently in the output buffer: 
status = ioctl (fd, FIOWFLUSH); 


Discards all the bytes currently in the input buffers: 
status = ioctl (fd, FIORFLUSH) ; 


Cancels a read or write. A task blocked on a read 
may have previously started a watchdog routine to 
time out the read. The watchdog would use this call 
on the appropriate fd: 


status = ioctl (fd, FIOCANCEL); 


Sets the baud rate of the device to the specified argu- 
ment. For example, the call: 


status = ioctl (fd, FIOBAUDRATE, 9600); 


Sets the device to operate at 9600 baud. This request 
has no meaning on a pseudo terminal. 


Returns TRUE for a tty device: 
status = ioctl (fd, FIOISATTY); 


Adds a protocol hook function to be called for each 
input character. pfunction is a pointer to the protocol 
hook routine which takes two arguments of type int 
and returns values of type STATUS (TRUE or FALSE). 
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The first argument passed is set by the user via 
FIOPROTOARG function. The second argument is 
the input character. If no further processing of the 
character is required by the calling routine (the input 
routine of the driver), the protocol hook routine 
pFunction should return TRUE. Otherwise, it should 
return FALSE: 


status = ioctl (fd, FIOPROTONOOK, p¥unction); 


FIOPROTOARG _ - Sets the first argument to be passed to the protocol 
hook routine set by FOPROTOHOOK function: 


status = ioctl (fd, FIOPROTOARG, arg); 


FIOBUFSET - Changes the size of the receive-side buffer to size: 
status = ioctl! (fd, FIOBSUFSET, size); 


Any other joctl() request will return an error, and set the status to 
S_ioLib UNKNOWN REQUEST. 


INCLUDE FILE 
tyLib.h 


SEE ALSO 
ioLib, iosLib, tyCoDrv, Programmer's Guide: I/O System 


NAME ; 
tyDevInit( ) - initialize the tty device descriptor 
SYNOPSIS 5 
STATUS tyDevinit (pTyDev, -rdBufSize; wrtBufSizse, txStartup) 
' ‘TY DEV_ID pTyDev; - /* pointer to-ty device descriptor */ 
/* to be initialized */ 
int rdBufSize; /* required read buffer size in bytes */ 
int wrtBufSizse; /* required write buffer size in bytes */ 
FUNCPTR txStartup; /* device transmit startup routine — a/ 
DESCRIPTION 


This routine initializes a tty device descriptor according to the specified 
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parameters. The initialization includes allocating read and write buffers of 
the specified sizes from the memory pool, and ini pubalang their respective 
buffer descriptors. The semaphores are initialized and the write semaphore 
is given to enable writers. Also, the transmitter start-up routine pointer is 
set to the specified routine. All other fields in the descriptor are zeroed. 


This routine should be called only by serial drivers. 


RETURNS 
OK, or ERROR if there is not enough memory to allocate data structures. 


SEE ALSO 
tyLib 


NAME 


tyA bortFuncSet{ ) - set the abort function 


SYNOPSIS 
VOID tyAbortFuncéet (func) 
FUNCPTR func; /* function to call when abort char is received */ 


DESCRIPTION oe 
This routine sets the sanction that will be called when the abort character is 
received on a tty. There is only one global abort function, used for any tty 
on which OPT _. ABORT is enabled;i When: the abort: character :is--received 
from a tty with OPT_ABORT ‘set, the:function: sec aos a3 ‘in n func will be called,- - 
with no parameters, from interruptlevelz: 222272"" 


Setting an abort function of NULE Gvill:disable the:abortifunction. - a. “te 


RETURNS ae set: y 8, i 
N/A | 


SEE ALSO 
tyLib, tyAbortSet{ ) 


Rev: 29 Aug 91 Intel 1 - 467 


Vx960 5.0 - Reference Manual 


aoe NeRe eee Meee 
SUES eae 


NAME 
tyAbortSet( ) - change the abort character 


SYNOPSIS 
VOID tyAbortSet (ch) 
char ch; /* character to be made the abort character */ 


DESCRIPTION | 
This routine sets the abort character to ch. The default abort character is “C. 


Typing the abort character to any device whose OPT_ABORT option is set 
will cause the shell task to be killed and restarted. Note that the character 
set by this routine applies to all devices whose handlers use the standard tty 
package tyLib. 


RETURNS 
N/A 


SEE ALSO 
tyLib, tyAbortFuncSet{ ) 


NAME 


tyBackspaceSet{ ) - change the backspace character | 


SYNOPSIS | 
VOID tyBackzpaceSet (ch) 
char ch; /* character to be made the backspace character */ 


DESCRIPTION i | 
This routine sets the backspace character to ch. The default backspace char- 
acter is “H. 


Typing the backspace character to any device operating in line protocol 
mode (OPT_LINE set) will cause the previous character typed to be deleted, 
up to the beginning of the current line. Note that the character set by this 
routine applies to all devices whose handlers use the standard tty package 
tyLib. 
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RETURNS 
N/A 


SEE ALSO 
tyLib 
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NAME 
ty DeleteLineSet( ) - change the line-delete character 


SYNOPSIS 
VOID tyDeleteLineSet (ch) 
char ch; /* character to be made the line—delete character */ 


DESCRIPTION 
This routine sets the line-delete character to ch. The default line-delete char- 
acter is “U. 


Typing the delete character to any device operating in line protocol mode 
(OPT_LINE set) will cause all characters in the current line to be deleted. 
Note that the character set by this routine applies to all devices whose 
handlers use the standard tty package tyLib. 


RETURNS 
N/A 


SEE ALSO 
tyLib 


NAME 
tyEOFSet{ ) - change the end-of-file character 


SYNOPSIS 
VOID tyzOFSet (ch) 
char ch; /* character to be made the eof character */ 


DESCRIPTION 
This routine sets the EOF character to ch. The default EOF character is ‘D. 
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Typing the EOF character to any device operating in line protocol mode 


(OPT _LINE set) will cause no character to be entered in the current line, but 
will cause the current line to be terminated (thus without a newline charac- 
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ter). The line is made available to reading tasks, Thus, if the EOF character 
is the first character input on a line, a line length of zero characters is 
returned to the reader. This is the standard end-of-file indication on a read 
call. Note that the EOF character set by this routine will apply to all devices 
whose handlers use the standard tty package tyLib. 


RETURNS 
N/A 


SEE ALSO 
tyLib 


NAME 
tyMonitorTrapSet( ) - change the trap-to-monitor character 


SYNOPSIS 


VOID tyMonitorTrapSet (ch) 
char ch; /* character to be made the monitor trap character */ 


DESCRIPTION 
This routine sets the trap-to-monitor character to ch. The default trap-to- 
monitor character is “X. 


Typing the trap-to-monitor character .to any device whose 
OPT_MON_TRAP option is set will cause the:resident ROM monitor to be 


entered, if one is:present:, Once.:the ROM: monitor is entered, the’ normal-~~ 


- Vx960 multitasking‘system ishalted. == 9 *~ 


Note that the trap-to-monitor character set by this routine will apply to all 
devices whose handlers use the standard tty package tyLib. Also note that 
not all systems have a monitor trap available. — 


RETURNS 
N/A 


SEE ALSO 
tyLib 
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NAME 
tyIoctl( ) - handle device control requests 


SYNOPSIS 


STATUS tyIoctl (pTyDev, request, arg) 
TY DEV ID pTyDev; /* pointer to device to control */ 


int request; /* request code w/ 
int arg} /* some argument «/ 
DESCRIPTION 


This routine handles ioctl( ) requests for tty devices. The I/O control func- 
tions for tty devices are described in the manual entry for tyLib. 


BUGS 
In line-protoecol mode (OPT_LINE option set), the FIONREAD function 
actually returns the number of characters available plus the number of lines 
in the buffer. Thus if five lines consisting of just NEWLINEs were in the 
input buffer, the FFONREAD function would return the value ten (five char- 
acters + five lines). 


RETURNS 
OK or ERROR. 


SEE ALSO 
tyLib 
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NAME sO 
tyWrite( ) - do a task-level write for a tty device 


SYNOPSIS 


int tyWrite (pTyDev, buffer, nbytes) 
TY DEV_ID pTyDev; /* pointer to device structure */ 


char «buffer; /* buffer of data to write «/ 
int nbytes; /* number of bytes in buffer */ 
DESCRIPTION 
This routine handles the task-level portion of the tty handlers write func- 
tion. 
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RETURNS 
The number of bytes actually written to the device. 


NAME | 
tyRead( ) - do a task-level read for a tty device 
SYNOPSIS | 
int tyRead (pTyDev, buffer, maxbytes) 
TY DEV ID pTyDev; /* device to read +/ 
char *buffer; /* buffer to read into «/ 
int maxbytes; /* maximum length of read */ 
DESCRIPTION 


This routine handles the task-level portion of the tty handler’s read function. 
It reads up to maxbytes available bytes into the buffer. 


This routine should only be called from serial device drivers. 


RETURNS 
The number of bytes actually read into the buffer. 


SEE ALSO 
tyLib 
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NAME 


tyITx({ ) - interrupt-level output 
SYNOPSIS 
STATUS tyITx (pTyDev, pChar) 
TY DEV_ID pTyDev; /* pointer to tty device descriptor «/ 
char *pChar; /* ptr where to put character to be output */ 
DESCRIPTION 


This routine gets a single character to be output to a device. It looks at the 
ring buffer for pTyDev and gives the caller the next available character, if 
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there is one. The character to be output is copied to pChar. 


RETURNS 
OK if there are more characters to send, or ERROR if there are no more char- 
acters. 


SEE ALSO 
tyLib 


NAME 


tyIRd( ) - interrupt level input 


SYNOPSIS 
STATUS tyIRd (pTyDev, inchar) 
TY DEV ID pTyDoev; /* pointer to tty device descriptor */ 
char inchar; /* character read «/ 


DESCRIPTION 
This routine handles interrupt-level character input for tty devices. A device 
driver calls this routine when it has received a character. This routine adds 
the character to the ring buffer for the specified device, and gives a sema- 
phore if a task is waiting for it. 


This routine also handles all the special characters, as specified in the option 
word for the device, such as X-on, X-off, NEWLINE, or backspace. ; 


RETURNS 
OK, or ERROR if the ring buffer is full. 


SEE ALSO 
 tyLib 
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NAME 
usrConfig - user-defined system configuration module 


SYNOPSIS 
usrInit( ) - user-defined system initialization routine 
usrRoot{( ) - the root task 
usrClock( ) - user-defined system clock interrupt routine 
usrScsiConfig() - configure a SCSI peripheral (example) 


VOID usrInit (startType) 
VOID usrfoot () 
VOID usxClock () 
STATUS usr&csiConfig () 


DESCRIPTION 
This is the Intel- -supplied configuration module for Vx960. It contains the 
root task, the primary system initialization routine, the network initializa- 
tion routine, and the clock interrupt routine. 


The include file config.h includes a number of system-dependent parame- 
ters used in this file. 


INCLUDE FILE 
config.h 


SEE ALSO | 
Programmer's Guide: Getting Started, Cis Deccan 
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usrInit( ) - user-defined system initialization routine 


SYNOPSIS 
VOID usrInit (startType) 
int startType; 


DESCRIPTION 
This is the first C code executed after the system boots. This routine is 
called by the assembly language start-up routine sysInit( ) which is in the 
sysALib module of the target-specific directory. It is called with interrupts 
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locked out. The kernel is not multitasking at this point. 


This routine starts by clearing BSS, so all variables are initialized to 0 as per 
the C specification. It then initializes the hardware by calling sysHwinit{ ), 
sets up the interrupt/exception vectors, and starts kernel multitasking with 
usrRoot( ) as the root task. 


RETURNS 


N/A 


SEE ALSO 


usrConfig, kernelLib_ 


NAME 


usrRoot( ) - the root task 


SYNOPSIS 


VOID usxRoot () 


DESCRIPTION 


_ This is the first task to run under the: ‘multitasking kernel: -It performs all 
final initialization and then starts other tasks. 


It initializes the I/O system, installs drivers, creates devices, and sets up the 


network, etc., as necessary for the particular. configuration. ‘It may:also.. =: 
create and load the system symbok table;: Lif one: istto=be!included:< It may °- - 
then load and spawn additional tasks Jen rieetiécia-the: oo a 


tion, it simply initializes the Vx960: Bhelhi siraiviy + ee ae 
N/A 

SEE ALSO 
usrConfig 
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NAME 

usrClock( ) - user-defined system clock interrupt routine 
SYNOPSIS 

VOID usxClock () 
DESCRIPTION 


This routine is called at interrupt level on each clock interrupt. It is installed 
by usrRoot{) with a sysClkConnect{ ) call. It calls all the other packages 
that need to know about clock ticks, including the kernel itself. 


If the application needs anything to happen at the system clock interrupt 
level, it can be added to this routine. 


RETURNS 
N/A 


SEE ALSO 
usrConfig 


NAME | 
usrScsiConfig() - configure a SCSI peripheral (example) 


SYNOPSIS 
STATUS usrScsiConfig () 


DESCRIPTION | | 
This routine is an example of how to declare a SCSI peripheral configura- 
tion. You must edit this routine to reflect the actual configuration of your 
SCSI bus. : 


If you are just getting started, you can test your hardware configuration by 
defining SCSI_AUTO_CONFIG in config.h, which will probe the bus and 
display all devices found. No device should have the same SCSI bus ID as 
your Vx960 SCSI port (default = 7), or the same as any other device. Check 
for proper bus termination. 


As an aid to debugging, either of the variables scsiDebug or scsiIntsDebug can 
be set to TRUE (1). When the hardware is working, be sure to undefine 
SCSL AUTO_CONFIG, Of course, you must rework the rest of this routine 
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to conform to your own hardware, as well as associated partitioning and file 
system mappings. 


In this example, there are two disk drives on the bus, an 80-Mbyte Winches- 
ter disk (ID=2, LUN=0) and a 1.2-Mbyte 5.25” floppy drive (ID=3, LUN=1). 
The floppy is actually interfaced via an OMTI 3500 universal SCSI-to-floppy 
adapter. 


The Winchester disk is divided into two 32-Mbyte partitions and a third par- 

tition with the remainder of the disk. The first partition is initialized as a 
dosFs device. The second and third partitions are initialized as rt11Fs dev- 
ices, each with 256 directory entries. 


It is recommended that the first partition (BLK_DEV) ona block device be a 
dosFs device, if the intention is eventually to boot ae from the device. 
This will simplify the task considerably. 


The floppy, since it is a removable medium device, is allowed to have only a 
single partition, and dosFs is the file system of choice for this device, since it 
facilitates media compatibility with IBM PC machines. 


While the Winchester configuration is fairly straightforward, the floppy 
setup in this example is a bit intricate. Note that the scstPhysDevCreate( ) 
call is issued twice. The first time is merely to get a “handle” to pass to the 
scsiModeSelect({ ) function, since the default media type is sometimes inap- 
propriate (in the case of generic SCSI-to-floppy cards). After the hardware is 
correctly configured, the handle is discarded via the scsiPhysDevDelete( ) 
call, after which a second scsiPhysDevCreate( ) call correctly configures the 
peripheral. (Before the scsiModeSelect( ) call, the configuration information 
was incorrect.) Also note that following the scsiBlkDevCreate() call, the 
correct values for sectorsPerTrack and nHeads must be set via the 
scsiBlkDevInit{ ) call. This is necessary for IBM PC compatibility. 


The last parameter to the dosFsDevInit() call is a pointer to a 
DOS_VOL_CONFIG structure. By specifying NULL, you are asking 
dosFsDevInit({ ) to read this information off the disk in the drive. This may 
fail if no disk is present or if the disk has no valid dosFs directory. Should 
this be the case, you can use the dosFsMkfs() command to create a new 
directory on a disk. This routine uses default parameters (see dosFsLib) that 
may not be suitable for your application, in which case you should use 
dosFsDevInit{ ) with a pointer to a valid DOS_VOL_CONFIG structure that 
you have created and initialized. If dosFsDevInit() is used, a diskInit( ) call 
should be made to write a new directory on the disk, if the disk is blank or 
disposable. : 
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NOTE | 
The variable pSbdFloppy is global to allow the above calls to be made from 
the Vx960 shell, i.e.: 


=> dosFsakkfs “/fd0/", p&bdFloppy 


If a disk is new, use diskFormat( ) to format it. 


RETURNS 
OK or ERROR. 


SEE ALSO 
usrConfig, Programmer's Guide: I/O System, Local File Systems 
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NAME 
usrLib - user interface subroutine library 


SYNOPSIS 
help( ) - print a synopsis of selected routines 
netHelp( ) - print a synopsis of network routines 
bootChange( ) - change the boot line 
periodRun( ) - call a function periodically 
period( ) - spawn a task to call a function periodically 
repeatRun( ) - call a function repeatedly 
repeat( ) - spawn a task to call a function repeatedly 
sp({ ) - spawn a task with default parameters 
checkStack( ) - print a summary of each task’s stack usage 
i( ) - print a summary of each task’s TCB 
ts( ) - suspend a task 
tr( ) - resume a task 
td( ) - delete a task 
ti( ) - print complete information from a task’s TCB 
version( ) - print Vx960 version information 
m() - modify memory 
d() - display memory 
cd() - change the default directory 
pwd() - print the current default directory 
copy() - copy in (or stdin) to out (or stdout) . | 
copyStreams() - copy from/to = streams: ; ~~ 
diskFormat(.) - format a disk ae 
diskInit( ) - initialize a file system ona. block device. 
squeeze() - reclaim fragmented free-space: onian:RT it coer 
Id() - load object module into. mem6ry }~ iezd.coject » raedrls tates 5 
Is() - list the contents of a directory’: ; ae ee Cee 
I1() - doa long listing of directory contents Enka 
IsOld( ) - list the contents of an RT-T1 directory. iene 
mkdir( ) - make a directory | 
rmdir() - remove a directory 
rm() - remove a file 
devs() - list all system-known devices 
Ikup() - list global symbols 
IkAdadr{ ) - list symbols whose values are near a given value 
pfp( ) - return the contents of register pfp (also sp, rip, r3-r15, g0-g14, fp) 
fp0( ) - return the contents of register fp0 (also fp1-3, 80960KB/SB only) 
pcw() - return the contents of the PCW register 
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tcw( ) - return the contents of the TCW register 

acw() - return the contents of the ACW register 

mRegs() - modify registers 

printErrno{ ) - print the definition of a specified error status value 
printLogo({ ) - print the Vx960 logo _ 

logout( ) - log out of the Vx960 system 

h( ) - display (or set) shell history ~ 


VOID help () 
VOID netHelp () 

VOID bootChange () 

VOID periodRun (secs, func, argl, arg2, arg3, arg4, arg5, .. 
int period (secs, func, argl, arg2, arg3, arg4, arg5, ... 
VOID repeatRun (n, func, argl, arg2, arg3, arg4, args, ... 
int repeat (n, func, argl, arg2, arg3, arg4, argS, ... 


int sp (func, argl, arg2, arg3, arg4, argS, arg6, arg7, arg8, arg) 


VOID checkStack (taskWemeOrcId) 
VOID 1 (taskNameOrId) 

VOID ts (taskNameOrId) 

VOID tr (taskiameOrId) 

VOID td (taskNameOrId) 

VOID ti (taskNameOrId) 

VOID version () 

VOID m (adrs) 

VOID d (adrs, nwords) 

STATUS cd (name) 

VOID pwd () 

STATUS copy (in, out) 

STATUS copyStreams (inFd, outFd) 
STATUS diskFormat (deviame) 
STATUS diskInit (deviame) 
STATUS squeeze (devName) 
STATUS 1d (syms, noAbort, name) 


. STATUS ls (dixtiame, doLong) 


STATUS 11 (dixrName) 
STATUS lsOld (dirName) 
STATUS mkdir (dirName) 
STATUS rmdir (dirName) 
STATUS rm (fileName) 
VOID devs () 

VOID lkup (substr) 
VOID LkAddr (addr) 
int pfp (taskId) 
double fpO (taskId) 
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int pow (taskId) 

int tow (taskId) 

int acw (taskId) 

STATUS mRegs (taskNameOrId) 
VOID printErrno (errno) 
VOID printLogo () 

VOID logout () 

VOID h (size) 


DESCRIPTION | 
This library consists of routines meant to be executed from the Vx960 shell. 
It provides useful utilities for task monitoring and execution, system infor- 
mation, symbol table management, etc. 


Many of the routines here are simply command-oriented interfaces to more 
general routines contained elsewhere in Vx960. Users should feel free to 
modify or extend this library. It may be preferable to customize capabilities 
by creating a new private library, using this one as a model, and appropri- 
ately linking it into the system. 


Some routines here have optional parameters. If those parameters are zero, 
which is what the shell supplies if no argument is typed, default values are 
typically assumed. 


A number of the routines in this module take an optional task name or ID as 
an argument. If this argument is omitted or zero, the ‘“‘current’’ task is used. 
The current task (or “default” task) is the last task referenced. usrLib uses 
taskIdDefault( ) to set and get the last-referenced task ID, as do many other 
Vx960 routines. 


SEE ALSO 
Programmer's Guide: Shell, Debugging 


NAME 


help() - print a synopsis of selected routines 


SYNOPSIS 
VOID help () 


DESCRIPTION 
This command prints the following list of the calling sequences for com- 
monly used routines, mostly contained in usrLib. 
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Print this list 

Print debug help info 

Print nfs help info 

Print network help info 

Print task histogramer help info 

Print execution timer help info 

Print (or set) shell history 

Summary of tasks’ TCEs 

Complete info on TCS for task 

Spam a task, pri=100, opt=-0, stk=20000 


taskSpawn name,pri,opt,stk,adr,args... Spawn a task 


help 
dbgHelp 
nfsHelp 
netHelp 
spyHelp 
timexKelp 
h [n] 
i [task] 
ti task 
sp adr,args... 
td task 
ts task 
tr task 
d [adr[ ,nwords] } 
m adr 
mRegs [task] 
r3-r15, gO-gl4 (task) 
fp0-fpl = [task] 
version . 
iam “user” [, "passwd" } 
whoaml 
od “path” 
aed 
devs 
is [“path"[, long) } 
11 [“path") 
rename “old”, “new 
copy [“in")[,“out") 


Delete a task 

Suspend a task 

Resume a task 

Display memory 

Modify memory 

Modify a task’s registers interactively 
Display a register of a task (80960ca version) 
Display a floating point register of a task (80960KB/ 
Print Vx960 version info, and boot line 

Set user name and passwd 

Print user name 

Set current working path 

Print working path 

List devices 

List contents of directory 


‘List contents of directory - long format 


Change name of file 
Copy in file to out file (0 = std in/out) 


1d [syms(,noAbort][,“name"}}] Load std in into memory 


lieup ("substr"} 
lkAddr address 
checkStack [task] 
printErrno value 


period secs ,adr, args... 


repeat n,adr,args... 


GiskFormat “device” 
diskinit “device” 
squeeze “device” 


(syms = add symbols-to: table: sosisin fasten cs | 
-1 = none, 0 = globals, 1 = all). i 

List symbols in system symbol table. -- . 

List symbol table entries near address: :..-_ 


List ‘task stack sizes and usage 
Print the name of a status value 


Speam task to call function periodically 

Spmm task to call function n times 
(0=f£orever ) 

Format disk 

Initialize file system on disk 

Squeeze free space on RT-11 device 


MOTE: Arguments specifying ‘task’ can be either task ID or name. 
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netHelp( ) - print a synopsis of network routines 


SYNOPSIS 


VOID netHelp () 


DESCRIPTION 


This command prints a brief synopsis of network facilities that are typically 
called from the shell. 


hostadd “hostname”, “inetaddr” - add a host-to-remote host table; 
“inetaddr" must be in standard 
Internet address format e.g. “90.0.0.4" 
hostShow - print current remote host table 
_netDevCreate “devname", “hostname”, protocol : ; 
- create an I/0 device to access 
files on the specified host 


| - (protocol O=reh, 1=ftp) dR rr A 
routeAdd “destaddr", “gateaddr"..- add route--to :-routestabie?” =-ice-2so%s se. 
routeShow ~- print current route table =... | 
iam “usr"[,"passwd"]- ~ specify the user. name by which?~2iiy-the uc. 

you will be know to remote i.you wlll ba. ten: 


hosts (and optional | password) ests =(andie< 


whoami : ie print the current remote ID*J#kis%. ti ace 

rlogin "host" . = log in toa remote host; -=-25y tact ux. 
"host" can be inet address or.286 wei wo 
host name in remote host table=:;. -- a 

ifshow [“Lfname" j - show info about network interfaces: — 

inetstatShow - show all Internet protocol sockets 

tcpstatsShow - show statistics for TCP 

udpstatShow - show statistics for UDP 

ipstatShow - show statistics for IP 

ianpstatShow - show statistics for IGP 

arptabShow ~ show a list of know ARP entries 
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mbu fghow - show mbuf statistics 


EXAMPLE : -> hostadd “mars”, “90.0.0.2" 
-> netDevCreate “mars:", "mars", O 


-> iam “fred” 
-> copy <mars:/etc/pasawd /* copy file from host “mars” * 
-> rlogin “mars" /* rlegin to host “mars“ * 
RETURNS 
N/A 
SEE ALSO 
| usrLib 


NAME 

bootChange( ) - change the boot line 
SYNOPSIS 

VOID bootChange () 
DESCRIPTION 


This routine is called to change the boot line used in the boot ROMs. This is 
especially useful during a remote login session. After changing the boot 
parameters, you can reboot the target with the reboot{ ) command. Then 
terminate your login (~. ) and remotely log in again. As soon as the system 
has rebooted, you will be logged in again. 


This routine stores the new boot line in non-volatile RAM, if the target has 
it. 

RETURNS 
N/A 


SEE ALSO 
usrLib 
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NAME 


periodRun( ) - call a function periodically 
SYNOPSIS 


VOID periodRun (secs, func, argl, arg2, arg3, argt, arg5, 
arg6, arg], arg8) 


int secs; /* pumber of seconds to delay between calls */ 

PUNCPTR func; /* function to call repeatedly «/ 

int argl, arg2,. arg3; /* args to pass to func «/ 

int arg4, arg5, arg6; /* args to pass to func «/ 

int arg], arg8; /* args to pass to func «/ 
DESCRIPTION 


This routine repeatedly calls a specified function, with up to eight of its 
arguments, delaying the specified number of seconds between calls. 


Normally, this routine is called only by period( ), which spawns it as a task. 


RETURNS 
N/A 


SEE ALSO 
usrLib, period( ) 


NAME 
period( ) - spawn a task to call a function periodically 


SYNOPSIS 
imt period (secs, func, argl, arg2, arg3, arg4, arg5, 
arg6, arg7, arg8) _ 
int secs; | /* period (in seconds) */ 
FUNCPTR func; /* function to call «/ 
int argl, arg2, arg3; /* args to pass to func */ 
int arg4, argS, arg6; /* args to pass to func */ 
int arg7, arg8; /* args to pass to func */ 
DESCRIPTION | 
This command spawns a task that will repeatedly call a specified function, 
with up to eight of its arguments, delaying the specified number of seconds 
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between calls. 
For example, to have i( ) display task information every 5 seconds, just type: 
=> period 5, i 


NOTE 
The task is spawned using the sp( ) routine. See the description of sp( ) for 
details about priority, options, stack size, and task ID. 


RETURNS 
A task ID, or ERROR if the task cannot be spawned. 


SEE ALSO 
usrLib, periodRun( ), sp() 


NAME 
repeatRun() - call a function repeatedly 


SYNOPSIS 
VOID repeatRun (n, func, argl, arg2, arg3, arg4, arg5, 
arg6, arg7, arg8) 


int n; /* # of times to call func (0=forever) */ 

FUNCPTR func; /* function to call repeatedly */ 

dint argl, arg2, arg3; /* args to pass to func «/ 

int arg4, argS, arg6;./* args to pass to func «/ 

; | int ‘arg7, arg; /* args to pass to func «/ 
DESCRIPT ION aie 


This routine calls: aSbieiliedk fertictiies naamnesiewith ere = its ‘argu-' 


ments. If 1 is 0, the routine if called dnaltesstipzs i eet 


' * o 
0% 
vrses 


_ Normally, this routine is called only by repeat(.), which spawns ‘it as a task. 


RETURNS ae 
N/A 


SEE ALSO 
usrLib, pent ) 
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NAME 
repeat() - spawn a task to call a function repeatedly 
SYNOPSIS 
int repeat (n, func, argl, arg2, arg3, arg4, arg5, 
arg6, arg], arg8) 
int n; /* @ of times to call function (0-forever) */ 
FUNCPTR func; /* function to call repeatedly «/ 
int argl, arg2, arg3; /* args to pass to func «/ 
int arg4, arg5, arg6; /* args to pass to func «/ 
int arg7, arg8; /* args to pass to func «/ 
DESCRIPTION 


This command spawns a task that will call a specified function n times, with 
up to eight of its arguments. If n is 0, the routine will be called endlessiy, or 
until the spawned task is deleted. 


NOTE 
The task is spawned using sp(). See the description of sp{ ) for details about 
priority, options, stack size, and task ID. 


RETURNS 
A task ID, or ERROR if the task cannot be spawned. 


SEE ALSO 
usrLib, repeatRun( ), sp( ) 
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NAME =e 
sp() - spawn a task with default parameters... 
SYNOPSIS 
int sp (func, argl, arg2, arg3, erga args, arg6, arg/, arg’, arg9) 
FUNCPTR func; /* function to call */ 
int argl, arg2, arg3; /* passed to spawned task */ 
int arg4, arg5, arg6é; /* passed to spammed task */ 
int arg7, arg8, arg9; /* passed to spesmed task */ 


Rev: 29 Aug 91 Intel 1 - 487 


OS. 


Vx960 5.0 —- Reference Manual 


DESCRIPTION 


This command spawns a specified function as a task with priority 100, the 
default options listed below, a 20000-byte stack, the highest task ID 
currently not used, and a default task name. The default options are: 


VX_FP._TASK - execute with floating point support 
VX_STDIO _ - execute with standard I/O support 
The task ID is displayed after the task is spawned. 


The default name assigned to the task is of the form “‘tr’’ where n is an 
integer which increments as new tasks are spawned, e.g,, £1, £2, £3, etc. 


This routine is a short form of the underlying taskSpawn() routine, con- 
_venient for spawning tasks in which the default parameters are satisfactory. 


If the default parameters are unacceptable, taskSpawn{) should be called 
directly. 


RETURNS 
A task ID, or ERROR if the task cannot be spawned. 


SEE ALSO 
usrLib, taskLib, taskSpawn( ) 
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NAME 
EERSTE ) - gb a summary of each task’s stack usage 


SYNOPSIS 
VOID checkStack (taskNameOrId) 
int taskNameOrId; /* task name or task ID, 0 = summarize all */ 


DESCRIPTION 
This command displays a summary of stack usage for a specified task, or for 
all tasks if no argument is given. The summary includes the total stack size 
(SIZE), the current number of stack bytes used (CUR), the maximum 
number of stack bytes used (HIGH), and the number of bytes never used at 
the top of the stack (MARGIN = SIZE - HIGH). For example: 


-> checkStack tShell 


AME ENTRY TID SIZE CUR HIGH MARGIN 


tShell shell 23e1c78 9208 832 3632 S576 
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The maximum stack usage is determined by scanning from the top of the 
stack for the first byte whose value is not Oxee. In Vx960, when a task is 
spawned, all bytes of a task’s stack are initialized to 


DEFICIENCIES 
It is possible for a task to write beyond the end of its stack, but not write 
into the last part of its stack, which will be undetected by checkStack( ). 


RETURNS 
N/A 


SEE ALSO 
usrLib, taskSpawn( ) 
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NAME 


i( ) - print a summary of each task’s TCB 


SYNOPSIS 
VOID i (taskHNameOrId) 
int taskHameOrId; /* task name or task ID, O = sumnarizse all «/ 


DESCRIPTION 
This command displays a synopsis of all the tasks in the system. The #() 
command provides more complete information on a specific task. 


EXAMPLE 

=> i 

MAME ENTRY TID PRI STATUS PC §P EBR2atO DELAY 
tExcTasx _excTask 20£cb00 O FED 200cS£ic 20fcab6c Oo 0 
tLogTask _logTask 20fb5b8 0 PEND 200c5fc 20£b520 +) ) 
tShell _shell 20efcac 1 READY 2014c90 200ef980 re) 0 
tRlogind rlogind 20£3£90 2 PEND 2038614 20£3db0 0 0 
tTelnetd _telnetd 20£2124 2 PEKD 2038614 20£2070 0 0 
tMetTask netTask 20£7398 50 PEND 2038614 20£7340 0] 0 


value = 57 = 0x39 = ‘9’ 
CAVEAT 


This routine should be used only as a debugging aid, since the information 


is obsolete by the time it is displayed. 
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RETURNS 
N/A 


SEE ALSO 
usrLib, fi( ) 
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NAME 
ts() - suspend a task 


SYNOPSIS 
VOID ts (taskNameOrId) 
int taskNameOrId; /* task name or task ID */ 


DESCRIPTION . 
This command suspends the execution of a specified task. It simply calls 


taskSuspend{ ). 


RETURNS 
N/A 


SEE ALSO 
usrLib, tr{ ), taskSuspend( ) 


NAME gS 
tr{ ) - resume a task 


SYNOPSIS | a 
VOID tr (taskNameOrId) =i; = | 
int taskNameOrId; /* task name or task ID */ 


DESCRIPTION | | | 
This command resumes the execution of a suspended task. It simply calls 


taskResume( ). 


RETURNS 
N/A 
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SEE ALSO 
ustLib, ts({ ), taskResume( ) 
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NAME 
td() - delete a task 


SYNOPSIS 
VOID td (taskNameOrId) 
int taskNameOrId; /* task name or task ID */ 


DESCRIPTION 
This command deletes a specified task. It simply calls taskDelete( ). 


RETURNS 
N/A 


SEE ALSO 
usrLib, taskDelete( ) 
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NAME | 
ti( ) - print complete information from a task’s TCB 


SYNOPSIS 
VOID ti (tasktMameOrId) “wade ep teh 2 
int taskNameOrid; /* task name or task 1D) O = use. default Wf ae ee eee 


DESCRIPTION 
This command prints the TCB contents, tntidlins registers, for a specified ~ TE Se 
task. If taskNameOrld is omitted or zero, the last‘task referenced is'assumed. **-?-*=*-*" 


EXAMPLE 
The following shows the TCB contents for the shell task: 
-> ti 
MAME ENTRY TID PRI STATUS PC sP ERRNO DELAY 
tMetTask _netTask  JTef2a0 50 PEND 1b064 7ef530 i) ) 
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stack: base 0x7ef450 end Ox7f1b60 size 9488 high 767 margin 8721 


options: Ox7 

VX_SUPERVISOR_MODE VX_UNBREAKABLE VX_DEALLOC STACK 

pfp: 7ef450 sp : 7ef530 rip: 1b064 £3: encececcec 
r4 : 0 75: esececssecee vr6 : eveoasee x7 : eoccceses 
r8 : eescecscce x9 : eoossece rl0: escscese r1i: Tef2a0 
x12: 16050 r13: ecsecscsesee rlé: escec9ese rl5: coesscece 
gO : 0 gl: 0 g2: Tef2za9 g3 : 318b8 
g4 : G gS: 0 g6 3: f£f£4£f££F£F g7 : ££ 
g8 : 0 gD : O gl: 0 glls 0 
gl2: 0 gl3: 7ef510 gl: 0 fp: Tef4d0 
pow: d&86088ff acw: 1102 tow: £001ff81 


ip +: 0x0 pow: Ox0 acw: 0x0 
Task: Ox7ef2a0 “tet Task" 
value = 26 = Oxla 

-> 


RETURNS 
N/A 


SEE ALSO 
usrLib, Programmer's Guide: Debugging 


NAME 


version( ) - print Vx960 version information 


SYNOPSIS _ | 
VOID version () 


DESCRIPTION 
This command prints the Vx960 version number, the date this copy of Vx960 


was made, and other pertinent information. 


EXAMPLE 
-> version 
Vx960 (for Beurikon HK80/V960@) version 5.0.2 
Kernel: WIND version 2.0. 
Made on Tue Jul 2 10:59:01 PoT 1991. 


Boot line: 
ei(0,0)mars: /usr/vww/oconfig/hkv960/vxWorks e-143.185.6.89 h=143.185.6. 
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9 u=target 
value = 103 = 0x67 = ’g’ 
-> 


RETURNS 
N/A 


SEE ALSO 
usrLib 


NAME 
m{) - modify memory 


SYNOPSIS 
VOID m (adrs) 
char *adrs; /* address to change * 


DESCRIPTION 
This command prompts the user for modifications to memory, starting at 
the specified address. It prints each address and the current contents of that 
address, in turn. The user can respond in one of several ways: 


RETURN - Do not change this address, but continue, a at the next 


address. 
number  - Set the content of this address to number. 
(dot) - Donot change this address, and quit. 
EOF _.- Donot change this address, and quit. 
All numbers entered and displayed are in hexadecimal. Memory is treated 
as 16-bit words. 
RETURNS 
N/A 
SEE ALSO 
usrLib, mRegs( ) 
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NAME 
d( ) - display memory 
SYNOPSIS | 
VOID d (adrs, nwords) 
char *adrs; /* address to display */ 
int nwords; /* number of words to print; if 0, use default */ 
DESCRIPTION 
This command displays the contents of memory, starting at adrs. If adrs is 
omitted, d() displays the next memory block, starting from where the last 
d( ) command completed. 
Memory is displayed in words. If nwords is zero or absent, the number of 
words displayed defaults to 64. If nwords is non-zero, that number of words 
is displayed and that number then becomes the default. The number of 
words d() displays is rounded up to the nearest number of full lines. 
RETURNS 
N/A 
SEE ALSO 
usrLib, m() 
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NAME : 
cd( ) - change the deféult-directorjnedefauitidixeters ii we ae 
SYNOPSIS a 
char *name; -'{* new directory name */- 
DESCRIPTION | 


This command sets the default directory to name. The default directory is a 
device name, optionally followed by a directory local to that device. 


To change to a different directory, specify one of the following: 


- an entire path name with a device name, possibly followed by a direc- 
tory name. The entire path name will be changed. 


- a directory name starting with a ~ or / or $. The directory part of the 
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path, immediately after the device name, will be replaced with the 
new directory name. 


- a directory name to be appended to the current default directory. The 
directory name will be appended to the current default directory. 


An instance of “’..”” indicates one level up in the directory tree. 


_ Note that when accessing a remote file system via rsh or ftp, the Vx960 net- 
work device must already have been created using netDevCreate( ). 


EXAMPLES 
The following example changes the directory to device “ /fd0/”’: 


=> od "/fd0/" 


This example changes the directory to device “mars:” with the local direc- 
tory “““leslie/vw’: 


=-> od “mars: leslie/vw" 


After the previous command, the TUEWING changes the sian to 
“mars: leslie /vw/config”’: ae 


-> od "config" 


After the previous command, the following changes the directory to 
“mars: leslie /vw/demo”’ 


-> od “../demo" 


After the previous command, the following. Changes - the: -directory:. to: 
“mars:/etc”’. | 


=> of “/etc" 


N ote that “ can be used only on ssiciciceaia iat orifipyec HWinkigigyior ghee oe 


RETURNS a 
OK or ERROR. 


SEE ALSO 
usrLib, pwd() 
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NAME 
pwd() - print the current default directory 


SYNOPSIS 
VOID pwd () 


DESCRIPTION 
This command displays the current working device /directory. 


RETURNS 
N/A 


SEE ALSO 
usrLib, cd( ) 


NAME 
copy() - copy in (or stdin) to out (or stdout) 


SYNOPSIS 
STATUS copy (in, cut) 
char tin; /* name of file to read (if MULL assume stdin) */ 
char tout; /* name of file to write (if HULL assume stdout) */ 


° 


DESCRIPTION 
This command copies from the input file to the output file, until an end-of- 


file is reached. 


EXAMPLES 
_ The following example displays the file “dog”, found on the default file dev- 


1ce: 


-> copy <dog 


This example copies from the console to the file “dog”, on device /ct0/, until 
an EOF (default “D) is typed: 


-> copy >/ct0/dog 


This example copies the file ““dog’, found on the default file device, to dev- 
ice /ctO/: 
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-> copy <dog >/ct0/dog 
This example makes a conventional copy from file named “‘file1"”’ to file 
named “‘file2”: | 

-> copy “filel", “file2" 


Remember that standard input and output are global; therefore, spawning 
the first three constructs will not work as expected. 


RETURNS 
OK, or ERROR if i or out cannot be opened/created, or if there is an error 
copying from in to out. 


SEE ALSO 
usrLib, copyStreams(), tyEOFSet{ ) 


NAME 


copyStreams( ) - copy from/to specified streams 


SYNOPSIS 
STATUS copyStreams (inFd, outFd) 
int inFd; /* file descriptor of stream to copy from */ 
int outFd; /* file descriptor of stream to copy to */ 


DESCRIPTION 
This routine copies from the stream identified by inFd to the stream identi- 
fied by outFd until an end of file is reached in inFd. This routine is used by 


copy(). 


RETURNS . 
OK, or ERROR if there is an error reading from inFd or writing to outFd. 


SEE ALSO 
usrLib, copy( ) 
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diskFormat( ) - format a disk 
SYNOPSIS 


STATUS diskFormat (devName) 
char *devilame; /* Meme of the device to initialize */ 


DESCRIPTION 
This command formats a disk and creates a file system on it. The device 
must already have been created by the device driver and initialized for use 
with a particular file system, via dosFsDevIntt( ) or rt11FsDevIntt{ ). 


This routine calls toctl( ) to perform the FODISKFORMAT function. 


EXAMPLE 
-> diskFormat "/fd0/" 


RETURNS 
OK, or ERROR if the device cannot be opened or formatted. 


SEE ALSO 
usrLib, dosFsLib, rt11FsLib 


NAME 


SYNOPSIS. °==8¥NOQ0". | 
STATUS diskInit (deviNahe) 
: Char *devName;  /* Mame of the device to initialize */ 


DESCRIPTION 
This command creates a new, blank file system on a block device. The dev- 
ice must already have been created by the device driver and initialized for 
use with a particular file system, via dosFsDevInit( ) or rt11FsDevInit, ). 


This routine calls ioctl() to — the FIODISKINIT function. 


EXAMPLE 
-> diskInit “/£d0/" 
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RETURNS 
OK, or ERROR if the device cannot be opened or initialized. 
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NAME 
squeeze( ) - reclaim fragmented free space on an RT-11 volume 


SYNOPSIS 
STATUS squeeze (devName) 
char *devName; /* RT-11 device to squeeze, e.g. */fd0/" */ 


DESCRIPTION 
This command moves data around on an RT-11 volume so that any areas of 
free space are merged. 


Note: No device files should be open when this procedure is called. The 
subsequent condition of such files would be unknown and writing to them 
could corrupt the entire disk. 


RETURNS 
OK, or ERROR if the device cannot be opened or squeezed. 


SEE ALSO 
usrLib 
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NAME 
Id( ) - load object module into memory 


SYNOPSIS 
STATUS 1d (syms, noAbort, name) 
int syms; /* =-1, 0, or 1 */ 
BOOL noAbort; /* TRUE = don’t abort script on error */ 
char *name; /* name of object module, MULL = standard input */ 
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DESCRIPTION 
This command loads an object module from a file or from standard input. 


The object module must be in GNU/960 b.out or coff format. External refer- 
ences in the module are resolved during loading. The syms parameter deter- 
mines how symbols are loaded; possible values are: 


0 - Add global symbols to the system symbol table. 
1. = - Add global and local symbols to the system symbol table. 
-1_ - Addno symbols to the system symbol table. 


If there is an error during loading (e.g., externals undefined, too many sym- 
bols, etc.), then shellScriptAbort( ) will be called to stop any script that this 
routine was called from. If noAbort is TRUE, errors are noted but ignored. 


The normal way of using ld() is to load all symbols (syms = 1) during debug- 
ging and to load only global symbols later. 


EXAMPLE 
The following example loads the b.out or coff file ““module’” from the default 


file device into memory, and adds any global symbols to the symbol table: 
-> 1d <module | 


This example loads “test.o” with all symbols: 
-> ld 1,0, “test.o" 


RETURNS 
OK, or ERROR if there are too many symbols, the object file format is 
invalid, or there is an error reading the file. 


SEE ALSO 
usrLib, loadLib 
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NAME 


Is() - list the contents of a directory 


SYNOPSIS 
STATUS ls (dirNeme, doLong) 
char *dixrName; /* name of dir to list */ 
BOOL doLong; /* if TRUE, do long listing */ 


1 - 500 intel | Rev: 29 Aug 91 


Ubrarles (1) usrLib 


DESCRIPTION 
This command is similar to UNIX Is. It lists the contents of a directory in 
one of two formats. If doLong is FALSE, only the names of the files (or sub- 
directories) in the specified directory are displayed. If doLong is TRUE, then 
the file name, size, date, and time are displayed. If doing a long listing, any 
entries that describe subdirectories will also be flagged with a “DIR” com- 
ment. 


The dirName parameter specifies the directory to be listed. If dirName is 
omitted or NULL, the current working directory will be listed. 


Empty directory entries and MS-DOS volume label entries are not reported. 


Is does not work with ftp or rsh network drives. Use IsOld instead. The 
error message for rsh or ftp network drives is ‘Can't open”. 


EXAMPLE 


=> ls “/usr/vw" 


RETURNS 
OK or ERROR. 


SEE ALSO 
usrLib, [I{ ), IsOld(), stat( ) 


NAME | 
Il() - do a long listing of directory contents 
SYNOPSIS 
STATUS 11 (dirkane) 
char «dirKame; /* newe of directory to list «/ 
DESCRIPTION 


This command causes a long listing of a directory’s contents to be displayed. 
It is equivalent to: SO 


-—> dirName="/usr/vw" 
—> 11 dixName, TRUE 


RETURNS 
OK or ERROR. 
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SEE ALSO 
usrLib, Is( ), stat( ) 
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NAME : | 
IsOld{( ) - list the contents of an RT-11, ftp, or rsh directory 
SYNOPSIS 
STATUS 1s0ld (dirHame) 
char *dirWame; /* device to list */ 
DESCRIPTION 


This is the old version of Is(), which used the old-style ioctl() function 
FIODIRENTRY to get information about entries in a directory. With Vx960 
release 5.0, this has been replaced with a new version of Is{) which uses 
POSIX directory and file functions. 


This version remains in the system to support certain drivers that do not 
currently support the POSIX directory and file functions. This includes 
netDrv, which provides the rsh and ftp mode remote file access (although 
nfsDrv, which uses NFS, does support the directory calls). Also, the new 
Is() no longer reports empty directory entries on RT-11 disks (i. e., the 
entries that describe unallocated sections of an RT-11 disk). | 


If no directory name is specified, the current working directory is listed. 


RETURNS 

OK, or ERROR if the directory cannot be opened. 
SEE ALSO oe ee . 
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NAME 
mkdir( ) - make a directory 


SYNOPSIS 
STATUS mkdir (dirKame) 
char *dirName; /« directory name */ 
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DESCRIPTION 
This command is provided for UNIX similarity. It works only on an NFS 
device. 


RETURNS 
OK, or ERROR if the directory cannot be created. 


SEE ALSO 
usrLib, rmdir( ) 
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NAME 
rmdir() - remove a directory 


SYNOPSIS 
STATUG rudir (dirHame) 
char *dirName} 


DESCRIPTION 
This command is provided for UNIX::similarity.:-It works only on an-NFS 
device. 


RETURNS | | 
OK, or ERROR if the directory cannot be removed. 


SEE ALSO 
usrLib, mkdir( ) eine 
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NAME 
rm()- remove a file 


SYNOPSIS 
STATUS rm (fileName) 
char *filelame; 


DESCRIPTION 
This command is provided for UNIX similarity. It simply calls delete( ). 
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RETURNS | 
OK, or ERROR if the file cannot be removed. 


SEE ALSO 
usrLib, delete( ) 
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NAME 


devs() - list all system-known devices 


SYNOPSIS 
VOID devs () 


DESCRIPTION | | 
This command displays a list of all devices known to the I/O system. 


EXAMPLE 

-> devs 

drv nome 
/null 
/tyCo/0 
/tyCo/1 


/pty/rlogin.s 
/pty/rlogin.M 
/pty/telnet .& 
/pty/telnet .h 

/ 

/usr 

o> 4. ° ai ts 


RETURNS 
N/A 


SEE ALSO 
usrLib, iosDevShow( ) . 
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NAME : 
Ikup( ) - list global symbols 
SYNOPSIS 
VOID lkup (substr) 
char *substr; /* substring to match */ 
DESCRIPTION | 


This command lists all symbols in the system symbol table whose names 
contain the string substr. If substr is omitted or is an empty string (""), all 
symbols in the table will be listed. 


This command also displays symbols that are local, i.e., symbols found in 
the system symbol table only because their module was loaded by /d( ). 


RETURNS 
N/A 


SEE ALSO 
usrLib, symLib, symEach( ) 


NAME 
IkAdadr( ) - list symbols whose values are near a given value 


SYNOPSIS 
VOID lkAddr (addr) 
unsigned int addr; /* address around which to look */ 


DESCRIPTION 
This command lists the symbols in the system symbol table that are near a 
specified value. The symbols that are displayed include: 


- symbols whose values are immediately less than the specified value 
- symbols with the specified value 
- succeeding symbols, until at least 12 symbols have been displayed 


This command also displays symbols that are local, i.e., symbols found in 
the system symbol table only because their module was loaded by Id{ ). 


Rev: 29 Aug 91 Intel 1 - 505 


Vx960 5.0 - Reference Manual 


RETURNS 
N/A 


SEE ALSO 


usrLib, symLib, symEach( ) 


NAME 
pfp() - return the contents of register pfp (also sp, rip, r3-r15, g0-g14, fp) 
SYNOPSIS 
int pfp (taskId) , 
int taskId; | /* task’s ID, 0 means default task */ 
DESCRIPTION 


This command extracts the contents of register pfp for a specified task from 
the task’s TCB. If taskId is omitted or 0, the current default task is used. 


The values are not guaranteed for the current executing task. 


The following similar routines are also available for accessing the contents 
of their associated registers: 


r3()-7115() —- alllocal registers 


gO )-g14()  - global registers 

tsp( ) - thestack pointer 
_rip() - the return instruction pointer 
fr) - the frame pointer | 


fp) -fp3() | - floating point xépisters (B0960KB. and 80960SB: ia 


 pew() - the processor control-word. . 
acw() - the arithmetic control word 
‘tew( ) - the trace control word 


NOTE 
To get the stack pointer of a task, use tsp(), because sp() (the logical name 
choice) conflicts with the routine sp{) for spawning a task with default 
| parameters. 


The return type for fp0( )-fp3() is double, not int. To get their return values 
printed out correctly on the shell command line, invoke them with the 
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appropriate cast (as described in the Programmer's Guide, section 9.3.1 Data 
Types). 
-> (double () ) fp0 ( taskId ) 


RETURNS 
The contents of the requested register. 


SEE ALSO 
usrLib, Programmer's Guide: Debugging 
80960CA User's Manual 
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NAME 
pcw( ) - return the contents of the PCW register 
SYNOPSIS 
| int pow (taskId) 
int taskId; /* task’s ID, 0 means default task */ 
DESCRIPTION 


This command extracts the contents of the PCW register for a specified task 
from the task’s TCB. If taskId is omitted or 0, the default task is used. 


RETURNS 
The contents of the register. 


SEE ALSO 
usrLib, Programmer's Guide: Debugging 80960CA-User's Manual _ 
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NAME 

tcw() - return the contents of the TCW register 
SYNOPSIS 

int tow (taskId) 


int taskId; /* task’s ID, 0 means default task */ 
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DESCRIPTION 
This command extracts the contents of the TCW register for a specified task 
from the task’s TCB. If taskId is omitted or 0, the default task is used. 


RETURNS 
The contents of the TCW register 


SEE ALSO 
usrLib, Programmer's Guide: Debugging 80960CA User's Manual. 
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NAME 
acw( ) - return the contents of the ACW register 
SYNOPSIS 
int acw (taskId) 
dint taskid; /* task’s ID, O means default task */ 
DESCRIPTION 


This Command extracts the contents of the ACW register for a specified task 
from the task’s TCB. If taskId is omitted or 0, the default task is used. 


RETURNS 
The contents of the ACW register. 


SEE ALSO 
usrLib, Programmer's Guide: Debugging 80960CA User's Manual. 
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NAME | 
mRegs( ) - modify registers 


SYNOPSIS 
STATUS mRegs (taskKemeOrId) 
int taskMameOrId; /* task name or task ID, 0 = default task */ 


DESCRIPTION | 
This command sequentially prompts the user for new values for a task’s 
registers. If taskNameOrld is omitted or zero, the last task referenced is 
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assumed. 


mRegs() prompts the user for modifications starting at register dO. It 
dispiays each register and the current contents of that register, in turn. The 
user can respond in one of several ways: 


RETURN - Do not change this register, but continue, prompting at the next 
register. 

number  - Set this register to number. 

.(dot) - Donot change this register, and quit. 

EOF - Donot change this register, and quit. 


All numbers are entered and displayed in hexadecimal, except floating-point 
values, which may be entered in double precision. 


RETURNS 
OK, or ERROR if the task does not exist. 


SEE ALSO 
usrLib, m() 
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NAME 
printErrno( ) - print the definition of a specified error status value 


SYNOPSIS 
VOID printErrno (errno) 
int errno; /* status code whose name is to be printed */ 


DESCRIPTION 
This command displays the error-status string, corresponding to a specified 
error-status value. It is only useful if the error-status symbol table has been 
built and included in the system. If errno is zero, then the current task status 


is used by calling errnoGet, ). 

This facility is described in errnoLib. 
RETURNS 

N/A 
SEE ALSO 


usrLib, errnoLib, errnoGet{ ) 
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NAME 

printLogo{ ) - print the Vx960 logo 
SYNOPSIS 

VOID printLogo () 
DESCRIPTION 


This routine displays the Vx960 banner seen at boot time. It also displays 
the Vx960 version number and kernel version number. 


RETURNS 
N/A 


SEE ALSO 
usrLib 
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NAME 
logout( ) - log out of the Vx960 system 


SYNOPSIS 
VOID logout () 
DESCRIPTION 


- This routine logs out of the Vx960 shell. If a remote login in active (via rlogin 
or telnet), it is stopped, arid standard I/O is restored to the console. 


SEE ALSO | 3 
usrLib, rlogin( ), telnet(), shellLogout( ) 
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NAME 
h() - display (or set) shell history 


SYNOPSIS 
VOID kb (size) 
int size; /* 0 = display, >0 then set history to new size */ 
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DESCRIPTION 
With no argument, this command displays Vx960 shell history. If size is 
specified, that number of the most recent commands will be saved for 
display. The value of size is initially 20. 


RETURNS 
N/A 


SEE ALSO 
usrLib, shellHistory(), ledLib 
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NAME 
vxA Lib - miscellaneous assembly language routines 


SYNOPSIS 
vxTas( ) - C-callable atomic test-and-set primitive 
BOOL vxTas (address) 


DESCRIPTION 
This module contains miscellaneous Vx960 support routines. 


SEE ALSO 
vxLib 
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NAME 
vxTas( ) - C-callable atomic test-and-set primitive 


SYNOPSIS 
BOOL, vxTas (eddress) 
char ‘address; /* address to be tested * 


DESCRIPTION 
This routine provides a C-callable interface to the i960 atomic-modify 
instruction. The “atmod” instruction is executed on the specified address. 


RETURNS 
TRUE if the value had not been set, but now is; FALSE if the value was 
already set. 

SEE ALSO 
vxALib 
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NAME 
vxLib - miscellaneous support routines 


SYNOPSIS 
vxMemProbe( ) - probe an address for bus error 
STATUS vxitemProbe (adrs, mode, length, pVal) 


DESCRIPTION 
This module contains miscellaneous Vx960 support routines. 


SEE ALSO 
vxA Lib 


SESSSE ; * sores ASISGA Sh soto 
Be ies pt EOE ee Re eawree ee SOU O ES 
Bs ks oA Sori PUL IIEL, 

CRRA RNR iene CRSA 
Sa Ro 


Zee, Crane 
Pee Sp Ary 


NAME 
vxMemProbe( ) - probe an address for bus error 
SYNOPSIS 
STATUS vxMemProbe (adrs, mode, length, pVal) 
char ‘*adrs; /* address to be probed ~ «/ 
int mode; /* READ or WRITE «/ 
int length; /* 1, 2, or 4 ; «/ 
char ‘*pVal; /* where to return value, «/ 
/* ox ptr to value to be written */ 
DESCRIPTION 


This routine probes a specified address to see if it is readable or writable, as 
specified by mode. The address will be read or written as 1, 2, or 4 bytes, as 
specified by length. (Values other than 1, 2, or 4 yield unpredictable results). 
If the probe is a READ, the value read will be copied to the location pointed 
to by pVal. If the probe is a WRITE, the value written will be taken from the 
location pointed to by pVal. In either case, pVal should point to a value of 1, 
2, or 4 bytes, as specified by length. 


Note that only bus errors are trapped during the probe, and that the access 
must otherwise be valid (i.e., not generate an address error). 
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EXAMPLE 
testMem (adrs) 
char tadra: 
{ 
char testW = 1; 
char testR; 
if (vxMemProbe (adrs, WRITE, 1, StestW) == OK) . ; 
printf (“value td written to adrs tx\n", testW, adrs); 
if (vxMemProbe (adrs, READ, 1, &testR) == OK) 
printf ("value td read from adrs tx\n", testR, adrs); 
} 
RETURNS 
OK if the probe is successful, or ERROR if the probe caused a bus error or an 
address misalignment. 
SEE ALSO 
vxLib 
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NAME 
wdLib - watchdog timer library 


SYNOPSIS 
wdCreate( ) - create a watchdog timer 
wadDelete( ) - delete a watchdog timer 
wdStart{ ) - start a watchdog timer 
wdCancel{ ) - cancel a currently counting watchdog 


WOOG_ID wiCreate () 

STATUS wiDelete (wdId) 

STATUS wiStart (wdId, delay, pRoutine, parameter) 
STATUS wiCancel (wdId) 


DESCRIPTION 
This library provides a general watchdog timer facility Any task may create 
a watchdog timer, then use it to provide events that can happen after a 
specified delay, outside the context of the task itself... 


Once a timer has been created with wdCreate(), it can be started with 
wdStart{ ). The wdStart( ) routine takes as parameters a timeout routine, an 
arbitrary timeout routine parameter, and a timeout in.ticks. (This will be the 


number of ticks as determined by the system-clock;-see sysCl kRateSet{ ) for 


more information.) After the specified delay ticks have elapsed, and if the 
timer has not been canceled with wdCancel(.), the timeout routine will be 


invoked with the parameter that was:specified-with.wdStart(). The timeout: ~ -:: 


routine will be invoked even if the Lia sabato ek the- Wakenaoe is-run- 
ning, suspended ordeleted. © fied fi: 


t =e 


Note that the timeout routine is eee ee ratherthan: inthe - 
_context:of the task. Therefore, it mustbéccareful:about :whatiticanand:can> =: «> 
not do... Watchdog routines are constrained tozthe:same=:rules-as ‘interrupt 


service routines. For example, they may-not take semaphores. -.- -’ - 


EXAMPLE 
WDOG ID wid = wdCreate Or 
wdStart (wid, 60, logMaeg, “Help, I’ve timed out!"); 
maybeSlowRoutine (); 
wdCancel (wid); 


In the above fragment, if maybeSlowRoutine() takes more than 60 ticks, 


logMsg( ) will be called with the string as a parameter, causing the message 
to be printed on the console. Normally, of course, more significant 
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corrective action would be taken. 


INCLUDE FILE 
wdLib.h 


SEE ALSO | 
logLib, Programmer's Guide: Basic OS, Cross-Development 


AAR OER ORE sonbsepeeN eS rts 
or ECHR NSN ASRS, ete olathe 


™ Se Ss fe 
ee 
Parent 


NAME 


wdCreate( ) - create a watchdog timer 


SYNOPSIS 
WOOG ID wiCreate () 


DESCRIPTION 
This routine creates a watchdog timer by allocating a WDOG structure from 
memory. 


RETURNS 
The ID for the watchdog created, or NULL if memory is insufficient. 


SEE ALSO 
wdLib 


NAME 


wdDelete( ) - delete a watchdog timer 


SYNOPSIS 
STATUS wiDelete (wild) | 
WOOG ID wdId; /* watchdog id to delete */ 


DESCRIPTION 
This routine de-allocates a watchdog timer. The watchdog will be removed 


from the timer queue if it has been started. This routine complements 
wdCreate( ). 
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RETURNS 
OK, or ERROR if the watchdog timer cannot be de-allocated. 


NAME 
wdStart{ ) - start a watchdog timer 


SYNOPSIS 


STATUS wdStart (wdId, delay, pRoutine, parameter) 

WOOG_ ID wdiId; /* watchdog id */ 

int | delay; /* delay count, in ticks */ 

once pRoutine; /* routine to call on time-out */ 

int \_ parameter; /* parameter with which to call routine */ 

DESCRIPTION WO b LGM f? va on 

This routine adds a watchdog timer to the system tick queue. The specified 
watchdog routine will be called from interrupt level after the specified 
number of ticks has elapsed. Watchdog timers may be started from inter- 
rupt level. Use wdCancel() to remove the watchdog from the system time 
queue. 


RETURNS 
OK, or ERROR if the watchdog timer cannot be started. 


SEE ALSO 
wd Lib, wdCancel( ) 
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NAME 
wdCancel( ) - cancel a currently counting watchdog 


SYNOPSIS 
STATUS wdCancel (wdId) 
wWOOG ID wdId; /* id of watchdog to cancel */ 
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DESCRIPTION | 
This routine cancels a watchdog timer that is currently running by zeroing 
its delay count. Watchdog timers may be canceled from interrupt level. 


RETURNS 
OK, or ERROR if the watchdog timer cannot be cancelled. 


SEE ALSO | 
wd Lib, wdStart{ 
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mb87030Lib 
memDrv 
netDrv 
nfsDrv 
pipeDrv 
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NAME 
mb87030Lib - Fujitsu mb87030 SCSI Protocol Controller (SPC) Library 


SYNOPSIS 
mb87030CtrICreate( ) - create a control structure for an mb87030 SPC 
mb87030CtriInit{ ) - initialize a control structure for an mb87030 SPC 
spcShow( ) - display the values of all readable mb87030 (SPC) registers 


MB 87030 _ SCSI_CTRL *mb87030CtriCreate (spcBaseAdrs, regOffset, clkPeriod, ... 
STATUS mb87030Ctrlinit (pSpc, scsiCtrlBusId, defaultSelTimeOut, scsiPriority) 
VOID spcShow (pSpc) 


DESCRIPTION 
This is the I/O driver for the Fujitsu. mb87030 SCSI Protocol Controller 
(SPC) chip. It is designed to work in conjunction with the scsiLib library. 


USER CALLABLE ROUTINES 
Most of the routines in this driver:are:accessible only through. the I/O sys- 
tem. Two routines, however,-must be called directly: mb87030CtrlCreate( )' 
to creaté a controller structure, ee mb87030€ trlInit{ ) to initialize the con- 
troller structure. 


INCLUDE FILES 
mb87030.h 


SEE ALSO 
scsiLib, Programmer's Guide: 1/0 System 
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NAME 


tb87030CtrICreate( ) - create'a-denttol’s 


SYNOPSIS 
MB _ 87030 SCSI_CTRL +mb97030Ctr1Create (spcBaseAdrs, regOffset, clkPeriod, 
spcDataParity, spcDmaBytesiIn, 


spcDmaBytesOut) 
UINTS *spcBaseAdrs } /* base address of the sFc */ 
int regOffset; /* address offset between consecutive regs. */ 
UINT elkPeriod; /* period of the controller clack (nsec) */ 
int apcDataParity; /* type of input to SPC DP (data parity) */ 
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FURCPTR spcDmaBytesIn; /* function for SCSI DMA input */ 
FUNCPTR spcDmaBytesOut; /* function for SCSI DMA output */ 


DESCRIPTION 
Before using the SPC chip, a data structure must be created by calling this 
routine. This routine should be called once and only once for a given SPC, 
and should be the first routine called, since it allocates memory for a struc- 
ture needed by all other routines in the library. 


After calling this routine, at least one call to mb87030CtrlInit( ) should be 
made before any SCSI transaction is initiated using the SPC chip. 


A detailed description of the input parameters follows: 


_spcBaseAdrs 
- the address at which the CPU would access the lowest (BDID) regis- 
ter of the SPC. 


regOffset 


- the address offset (bytes) to access consecutive registers. (This must 
be a power of 2, for example, 1, 2, 4, etc.) 


clkPertod 
- period in nanoseconds of the signal to SPC CLK input (only used for 
select timeouts). 


spcDataParity 
- must be one of: 
SPC_DATA_PARITY_LOW 
SPC_DATA_PARITY_HIGH 
SPC_DATA_ PARITY VALID 
according to whether the input to SPC DP is GND, +5V, or a valid 
parity signal. 
spcDmaBytesIn and spcDmaBytesOut 
- board-specific routines to handle DMA input and output; if these are 
_ NULL (0), SPC program transfer mode is used: DMA is possible only 
Se during SCSI data in/out phases. The interface to these DMA routines 
| | must be of the form: 


STATUS xxDmaBytes{In, Out} (pScsiPhysDev, pBuffer, bufLength) 


SCSI_PHYS DEV *pScsiPhysDev; ae ptr to phys dev info * 
UINTS *pBuffer; /* ptr to the data buffer * 
int bufLength; /* number of bytes to xfer * 


RETURNS 
A pointer to the SPC control structure, or NULL if memory is unavailable or 
there are bad parameters. 
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SEE ALSO 
mb87030Lib 
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NAME 
mb87030CtrlInit{ ) - initialize a control structure for an mb87030 SPC 
SYNOPSIS 
STATUS wmb87030CtrlInit (pSpc, scsiCtrlBusId, defaultSelTimeOut, scsiPriority) 
MB_ 87030 SCBSI_CTRL *pSpc; /* ptr to SPC struct */ 
int sceiCtrlBusId; /* SC8SI bus ID of this SPC */ 
UIRT defaultSelTimeOut; /* default device select time-out (usec) * 
int sceiPriority; /* priority of a task when doing sCSI 1/0 
DESCRIPTION 


After an SPC control structure is created with mb87030CtrICreate( ), it must 
be initialized by calling this routine before using the SPC. It may be called 
more than once if desired. However, it should only be called while there is 
no activity on the SCSI interface, since the specified configuration is written 
to the SPC. 


Before returning, this routine pulses RST (reset) on the SCSI bus, thus reset- 
ting all attached devices. 


A detailed description of the input parameters follows: 


pSpce- pointer to the MB _87030_SCSI_CTRL structure created with 
mb87030CtrICreate( ). | 


scsiCtrlBusld 
- the SCSI bus ID of the SPC. The ID is somewhat arbitrary (ranges 
between 0-7); the value 7, or highest priority, is usually assigned. 


defaultSelTimeOut 
- the timeout (in microseconds) for selecting a SCSI device attached to 
this controller, called default since the timeout may be specified for 
each device (see the manual entry for scsiPhysDevCreate()). The 
recommended value 0 specifies SCSI DEF SELECT TIMEOUT (250 
ms). The maximum timeout possible is approximately 3 seconds. 
Values that exceed this revert to the maximum. 
scstPriority 
- the priority to which a task is set when performing a SCSI transaction 
(ranging from 0 to 255). Otherwise, the value -1 indicates that the 
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priority should not be altered during SCSI transactions. 


RETURNS 
OK, or ERROR if any parameters are out of range. 
SEE ALSO 
mb87030Lib 
ERE - ig a 34 = ee pesecraapees 
SS, ee 


NAME 
spcShow( ) - display the values of all readable mb87030 (SPC) registers 


SYNOPSIS 
VOID spcShow (pSpc) 
MB_ 87030 SCSI_CTRL ‘*pSpc; /* ptr to SPC struct */ 


DESCRIPTION | | 
This routine displays the:state: of the SPC-registers in a user-friendly way. It 
is useful primarily for debugging. 

RETURNS | 
N/A 


SEE ALSO 
mb87030Lib 
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memDrv - pseudo memory device driver 


SYNOPSIS 


memDrv({ ) - install a memory driver 
memDevCreate( ) - create a memory device 


STATUS meewDrv () 
STATUS memDevCreate (name, base, length) 


DESCRIPTION 


This driver allows the I/O system to access memory directly as a pseudo- 

I/O device. Memory location and size are specified when the device is 
created. This feature is useful when data must be preserved between boots 

of Vx960 or when sharing data between CPUs. This driver does not imple- 
ment a file system as does ramDrv. The ramDrv driver. must be given 
memory over which it has absolute control; memDrvy simply provides ‘a: 
high-level method of reading and writing bytes: in-absolutesmemory* istine: ligt 
tions through I/O calls. 


USER-CALLABLE ROUTINES 


lOCTL 


Most of the routines in this adver are accessible only through the I/O sys- 
tem. Two routines, however, must be:called directly:-memDrv{ ) to initialize Ses 
the driver, and memDevCreate{ ) to create devices. | 


Before using the driver, it must be initialized. by- calling: memDro{ 2: Thisa::: 
routine should be called only-.orice,;: before: any reads, writesjror::S<!6 
memDevCreate() calls. It may be called from earns ):in usrConfig-c-or-at=e75 =, 


some later point. 


The memory siete nmin to: as ee tener aaa FOsecifiy 
WHERE. | 


SEE ALSO 


Programmer's Guide: I/O System 
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NAME 
memDrv{ ) - install a memory driver 


SYNOPSIS 
STATUS mewDrv () 


DESCRIPTION | 
This routine initializes the memory driver. It must be called first, before any 
other routine in the driver. 


RETURNS 
OK, or ERROR if the I/O system cannot install the driver. 


SEE ALSO 
memDrv 


NAME 
memDevCreate( ) - create a memory device 


SYNOPSIS 
STATUS memDevCreate (name, base, length) 
char ‘*name; /* device name */ 
-° char ‘tbase; /* where to start in memory */ 
int length; /* number of bytes */ 


DESCRIPTION 
This routine creates a memory davies Memory for the device is simply an 
absolute memory location beginning at base. The length pee indicates 
the size of memory. 


For example, to create the device ““/mem/cpu0/”, a device for accessing the 
entire memory of the local processor, the proper call would be: 


memDevCreate ("/mem/cpu0/", LOCAL MEM LOCAL ADRS, sysiemTop()) 


The device is created with the specified name, start location, and size. 
LOCAL MEM_LOCAL_ADRS is target specific and is defined in config.h. 


To open a file descriptor to the memory, use open(). Specify a pseudo-file 
name of the byte offset desired, or open the “raw’ file at the beginning and 
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specify a position to seek to. For example, the following call to open() 
allows memory to be read starting at decimal offset 1000. 


-> fd = open ("/mem/cpu0/1000", O_RDONLY, 0) 


Pseudo-file name offsets are scanned with “%d’’. 


EXAMPLE 
Consider a system configured with two CPUs in the backplane and a 
separate dual-ported memory board, each with 1 megabyte of memory. The 
first CPU is mapped at VMEbus address 0x00400000 (4 Meg.), the second at 
bus address 0x00800000 (8 Meg.), the dual-ported memory board at 
0x00c00000 (12 Meg.). Three devices can be created on each CPU as follows. 
On processor 0: 


-> memDevCreate ("/mem/local/", 0, sysMamTop() ) 
-> memDevCreate ("/mem/cpul/", 0x00800000, 0x00100000) 
-> memDevCreate ("/men/share/", 0x00c00000, 0x00100000) 


On processor 1: 
-> memDevCreate ("/mem/local/", 0, sysMemTop()) 


-> memDevCreate ("/mam/cpu0/", 0x00400000, 0x00100000) 
-> memDevCreate ("/men/share/", 0x00c00000, 0x00100000) 
Processor 0 has a local disk. Data or an object module needs to be passed 


from processor 0 to processor 1. To accomplish this, processor 0 first calls: 
-> copy </diskl/module.o >/mem/share/0 


Processor 1 can then be given the load command: 
-> ld </men/share/0 


RETURNS 
OK, or ERROR if memory is insufficient or the I/O system cannot add the 
device. 


SEE ALSO 
memDrv 
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NAME 


netDrv - network remote file I/O driver 


SYNOPSIS 
netDrv{ ) - install the network remote file driver 
netDevCreate({ ) - create a remote file device 


STATUS netDrv () 
STATUS netDevCreate (devName, host, protocol) 


DESCRIPTION 
This driver provides facilities for accessing files transparently over the net- 
work via ftp or rsh (see nfsLib for file access via NFS). By creating a network 
device with netDevCreate(), files on a remote UNIX machine may be 
accessed as if they were local. 


When a remote file is opened, the entire file is copied over the network to a 
local buffer. When a remote file is created, an empty local buffer is opened. 
Any reads, writes, or ioctl( ) calls are performed on the local copy of the file. 
If the file was opened with the flags O_WRONLY or O_RDWR and modi- 
fied, the local copy is sent back over the network to the UNIX machine when 
the file is closed. 


Note that this copying of the entire file back and forth can make netDrv 
devices awkward to use. A preferable mechanism is NFS as provided by 
nfsDrv. 


USER-CALLABLE ROUTINES 
Most of the routines in this driver are accessible only os the I/O sys- 
tem. However, two routines. must be:called: directly: aie ito herpes : 
the driver and ii cinta aonidate cuit ©. eo 4 


FILE OPERATIONS 
This driver supports’ the eaten, deletion; opening;. oe writing, sles : 
appending of files. The renaming of files‘is not supported.. : : 


INITIALIZATION | 
Before using the driver, it-must-be initialized‘by calling the routine netDrv\ ). 
This routine should be called exactly once, before any reads, writes, or calls 
to netDevCreate(). If INCLUDE_NETWORK is defined in configAILh, it is 
called from usrRoot( ) in usrConfig.c. 


CREATING NETWORK DEVICES 
To access files on a remote host, a network device must be created by calling 
netDevCreate(). The arguments to netDevCreate() are the name of the 
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device, the name of the host the device will access, and the remote file access 
protocol to be used — rsh or ftp. By convention, a network device name is 
the remote machine name followed by a colon “:". For example, for a UNIX 
host on the network “vxhost”, files can be accessed by creating a device 
called ‘‘vxhost:’”’. See the anal entry for netDevCreate() for more infor- 


mation. 


FUNCTIONS 
The network driver responds to the following ioctl() functions: 


FIOGETNAME =- Gets the file name of the fd and copies it to the buffer 
specified by nameBuf. 
status = ioctl (fd, FIOGETMAME, GnameBuf); 


FIONREAD - Copies to nBytesUnread the number of bytes remaining 
in the file specified by fd: 


status = ioctl] (fd, FIOMREAD, ankytesUnread) ; 


FIOSEEK - Sets the current byte offset in the file to the position 
) specified by newOffset. If the seek«goes beyond the 


end-of-file,, the file grows. Therend-of-file. pointer . 


changes to the new position, and the:new: space’is filled. 
with zeroes: 


status = ioctl (fd, FIOSEEK, newOffset); 


FIOWHERE - Returns the current byte position in:the:file..This:is:the-.. . 
byte offset of the next byte to: be: eae! or-written. It... -.. 


takes no additional argument: 


position = eee (fd, rata ac via 8 Aan Ff 


SEE ALSO 2 


remLib, netLib, sockLib, hostAdd(}j Programmer's. Guide: iNefworki 
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netDrv{ ) - install the network remote file driver 


SYNOPSIS 
STATUS netDrv () 


DESCRIPTION 
This routine initializes and installs the network driver. It must be called 
before other network remote file functions are performed. If 
INCLUDE_NETWORK is defined in configAILh, it is called from usrRoot{ ) 
in usrConfig.c. 


RETURNS 
OK or ERROR. 


SEE ALSO 
netDrv 


NAME 
netDevCreate( ) - create a remote file device 


SYNOPSIS , 
STATUS netDevCreate (devNams, host, protocol) 
char ‘*deviName; /* name of device to create */ 
char *host; /* host this device will talk to */ 
int protocol; /* remote file access protocol */ 
/* 0 = RSH, 1 = FIP */ 


DESCRIPTION 
This routine creates a remote device. Normally, a network device is created 
for each remote machine whose files are to be accessed. By convention, a 
network device name is the remote machine name followed by a colon “:”’ 
For example, for a UNIX host on the network whose name is “vxhost’”’, files 
can be accessed by creating a device called “‘vxhost:’’. Files can be accessed 
via rsh as follows: 


netDevCreate ("“vxhost:", “vxhost", rsh); 
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The file /usr/dog on the UNIX system “vxhost’’ can now be accessed as 
“‘vxhost:/usr/dog’”’ via rsh. 


Before creating a device, the host must have already been created with 
hostAdd( ). 


RETURNS 
OK or ERROR. 


SEE ALSO 
netDrv, hostAdd( ) 
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NAME 


nfsDrv - Network File System I/O driver 


SYNOPSIS 
nfsDrv{ ) - install the NFS driver 
nfsMount( ) - mount an NFS file system 
nfsMountAll( ) - mount all file systems exported by a specified host 
nfsDevShow( ) - display the mounted NFS devices 
nfsUnmount( ) - unmount an NFS device 


STATUS nfsDrv () 

STATUS nfsMount (host, fileSystem, localName) 
STATUS nfsMountAll (host, clientName, quiet) 
VOID nfsDevShow () 

STATUS nfsUnmount (localName) 


DESCRIPTION 
This driver provides facilities for transparently accessing files over the net- 
work via the Network File System (NFS). By creating a network device with 
nfsMount( ), files on a remote NFS system (such as a UNIX system) can be 
handled as if they were local. 


USER-CALLABLE ROUTINES 
nfsDrv{ ) is called to initialize the driver; nfsMount{ ) is called to mount file 
systems; and _— ) is called to unmount them. 


INITIALIZATION 
Before using the network driver, it must be-initialized by calling. xfsDrv(). . 
This routine must be-called: before ‘any reads; writes; or other: NFS*‘calls. - If -- 
INCLUDE _NFS is ‘defined ‘in config Alli i caller maroon 
usrConfig.c. ord FO at ore sae 


CREATING NFS DEVICES 
In order to access a remote file syle an NFS:device: must be created by 
calling fsMount( ). For example, to create the device “ f ae ’* for the file 
system “/d0/’ on the host “‘vxhost”, call: 


nfsMount ("“vxhoet", "/d0/", "/myd0/"); 
The file “140 /dog” on the host “vxhost’” can now be .accessed as 
“/myd0/dog”. 


If the third parameter to nfsMount{( ) is NULL, Vx960 creates a device with 
the same name as the file system. For example, the call: 
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nfsMount ("vxhost", "/d0/", MULL); 


or from the shell: 
nfsMount “vxhost", "/d0/" 


creates the device ““/d0/". The file ““/dOQ/dog” is accessed by the same 
name, “ /d0/dog’’. 


Before mounting a file system, the host must have been already created with 
hostAdd(). The routine sfsDevShow( ) displays the mounted NFS devices. 


lOCTL 
The NFS driver responds to the following ioctl( ) functions: 


FIOGETNAME =. Gets the file name of fd and copies it to the buffer refer- 
enced by nameBuf: 


status = ioctl (fd, FIOGETNAME, &nameBuf) ; 


FIONREAD - Copies to nBytesUnread the number of bytes remaining 
in the file specified by fd: 


status = ioctl (fd, FIONREAD, GnBytesUnread) ; 


FIOSEEK - Sets the current byte offset in the file to the position 
specified by newOffset. If the seek goes beyond..the> 
end-of-file, the file grows. The end-of-file pointer gets. 
moved to the new position, and the new space is filled 
with zeros: 


status = ioctl (fd, FIOGEEK, newOffset); — 


FIOWHERE - Returns the current byte. position dnithe:fi seaman POCSi 
byte offset of the next byte to be: read® or: wriften.= Ht Pte 
takes no additional argument: : | : 


position = ioctl (fd, FIOMHERE) ; 


FIOREADDIR ~~ - Reads the next directory entry. The argument dirStruct . --- 
is a pointer to a DIR directory descriptor. Normally, the 
readdir( ) routine is used to read a directory, rather than 
using the FIOREADDIR function directly. See the 
manual entry for dirLib: | 


DIR dirStruct; 
fd = open (“directory”, READ); 
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status = ioctl (fd, FIOREADDIR, é&dirStruct); 


FIOFSTATGET - Gets file status information (directory entry data). The 
argument statStruct is a pointer to a stat structure that is 
filled with data describing the specified file. Normally, 
the stat{ ) or fstat() routine is used to obtain file infor- 
mation, rather than using the FIOFSTATGET function 
directly. See the manual entry for dirLib: 


struct stat statStruct) 
fd = open ("file", READ); | 
status = ioctl (fd, FIOFPSTATGET, &statStruct); 


DEFICIENCIES 
There is only one client handle/cache per task. Performance is poor if a task 
is accessing two or more NFS files. _ 


Changing the nfsCacheSize variable after a file is open could cause adverse 
effects. However, changing it before opening any NFS file descriptors 
should not pose a problem. nfsCacheSize is of type unsigned integer. 


SEE ALSO 
dirLib, nfsLib, hostAdd{ ), ioctl( ), Programmer's Guide: Network 
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NAME 
nfsDrv( ) - install the NFS driver 


SYNOPSIS 


STATUS nfsDrv () 


DESCRIPTION 
This routine initializes and installs the NFS driver. It must be called before 
any other NFS calls. If INCLUDE_NFS is defined in configAILh, it is called 
from usrRoot( ) in usrConfig.c. 


RETURNS 
OK, or ERROR if there is no room for the driver. 


SEE ALSO 
nfsDrv 
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NAME 
nfsMount{ ) - mount an NFS file system 
SYNOPSIS 
STATUS ufadMount (host, fileSystem, local Name) 
char *host; /* neme of remote host w/ 
char ‘*fileSystem; /* name of remote directory to mount «/ 
char ‘localName; /* local device name for remote directory */ 
/* (WULL = use fileGystem name) «/ 
DESCRIPTION 


This routine mounts a remote file system. It creates a local device localName 
for a remote file system on a specified host. The host must have already 
been added to the local host table with hostAdd(). If localName is NULL, the 


local name will be the same as the remote name. 


RETURNS 
OK, or ERROR if the driver is not installed, host is invalid, or the system is 


out of memory. 


SEE ALSO 
nfsDrv, nfsUnmount( ), hostAdd( ) 
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NAME 
nfsMountAll( ) - mount all file systems exported by a specified host 


SYNOPSIS 
| STATUS nfsMountAll (host, clientNeme, quiet) 
char *host; /* name of remote host */ 
char ‘*clientName; /* name of client specified in access list */ 
BOOL quiet; /* FALSE = print names of file systems mounted */ 


DESCRIPTION 
This routine mounts the file systems exported by host which are marked as 
accessible by either all clients or only clientName. The nfsMount( ) routine is 
called to mount each file system. This creates a local device for each 
mounted file system that has the same name as the file system. 


The file systems are listed to standard output as they are mounted. 
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RETURNS 
OK, or ERROR if any mounts failed. 


SEE ALSO 
nfsDrv, nfsMount( ) 
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NAME 
nfsDevShow( ) - display the mounted NFS devices 


SYNOPSIS 
VOID nfsDevShow () 


DESCRIPTION 
This routine displays the device names and their associated NFS file sys- 
tems. For example: 


-> nfsDevShow 
device name file system 


/yubal/ yuba: /yubal 
/wuhost1/ vzhost : /yxhostl 


RETURNS 
N/A 


SEE ALSO 
nfsDrv 
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NAME | 
nfsUnmount( ) - unmount an NFS device 


SYNOPSIS 
STATUS nfsUnmount (local ame) 
char ‘localiiame; /* local of nfs device */ 


DESCRIPTION 
This routine unmounts file systems that were previously mounted via NFS. 
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RETURNS 
OK, or ERROR if localName is not an NFS device or cannot be mounted. 


SEE ALSO 
nfsDrv 
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NAME 


pipeDrv - pipe I/O driver 


SYNOPSIS — 
pipeDrv{ ) - initialize the pipe driver 
pipeDevCreate( ) - create a pipe device 


STATUS pipeDrv () 
STATUS pipeDevCreate (name, nMessages, nBytes) 


DESCRIPTION 
Pipes are virtual devices that let tasks communicate with each other through 
the standard I/O interface. Pipes can be read and written with normal 
read() and write( ) calls. The pipe driver is initialized with pipeDrv(). Pipe 
devices are created with pipeDevCreate( ). 
The pipe driver uses the Vx960 message queue facility to do the actual 
buffering and delivering of the messages. The pipe driver simply provides 


access to the message queue facility through the I/O system. The main 
differences between using pipes and using message queues directly are: 


- pipes are named (with I/O device names). 


pipes use the standard I/O functions — open( ), close(), read( ), write() 
— while message queues use the functions msgQSend() and 
msgQReceive( ). 


pipes respond to standard ioctl() functions. 


pipes can be used in a select( ) call. 


message queues have more flexible options for timeouts and message 
priorities. 


pipes are less efficient than message queues because of the additional 
overhead of the I/O system. 


INSTALLING THE DRIVER 
Before using the driver, it must be initialized and installed by calling 
pipeDrv{ ). This routine must be called before any pipes.are created. If 
INCLUDE_PIPES is defined in configAll.h, it is called by the root task 
usrRoot( ) in usrConfig.c. | 


CREATING PIPES 
Before a pipe can be used, it must be created with pipeDevCreate(). For 
example, to create the device pipe “ /pipe/demo” with up to 10 MESta ees of 
size 100 bytes, the proper call would be: 
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pipeDevCreate ("/pipe/demo", 10, 100); 


USING PIPES 
Once a pipe has been created it can be opened, closed, read, and written just 
as any other I/O device. Often the data that is read and written to a pipe is 
a structure of some type. Thus, the following example writes to a pipe and 
reads back the same data: 


{ 

int fd; 

struct mag outMeg; 
struct msg inNsg; 
int len; 


fd = open ("/pipe/demo", O RDUR); 


write (fd, &outMsg, sizeof (struct msg) ); 
len = read (fd, GinkMsg, sizeof (struct msg) ); 


close (fd); 
} 


The data written to a pipe is kept as a single message and will be read all at 
once in a single read. If read{ ) is called with a buffer that is smaller than the 
message being read, the remainder of the message will be discarded. Thus, 
pipe I/O is ‘‘message-oriented” rather than “‘stream-oriented’’. In this 
respect, they differ significantly from UNIX pipes which are stream-oriented 
and do not preserve message boundaries. 


WRITING TO PIPES FROM INTERRUPT SERVICE 

Interrupt service routines can write to pipes providing one of several ways 
in which interrupt service routines can communicate with tasks. For exam- 
ple, an interrupt service routine may handle the time-critical interrupt 
response and then send a message on a pipe to a task that will continue with 
the less critical aspects. However, the use of pipes to communicate from an 
ISR to a task is now discouraged in favor of the direct message queue facil- 
ity, which offers lower overhead (see msgQLib for more information). 


SELECT CALLS | | 
An important feature of pipes is their ability to be used in a select() call. 
The select() routine allows a task to wait for input from any of a selected set 
of I/O devices. A task can use select() to wait for input from any combina- 
tion of pipes, sockets, or serial devices. See the manual entry for select( ). 


IOCTL FUNCTIONS 
Pipe devices respond to the following ioc#tl( ) functions. These functions are 
defined in the header file ioLib.h. 
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- Gets the file name of fd and copies it to the buffer refer- 


FIOGETNAME 
enced by nameBuf. 
status = ioctl (fd, FIOGETMAME, é&nameBuf) ; 


FIONREAD Copies to nBytesUnread the number of bytes remaining 
in the pipe: 
status = ioctl (fd, FIONREAD, &nBytesUnread) ; 


Copies to nMessages the number of discrete messages 


FIONMSGS - 
remaining in the pipe: 
status = ioctl (fd, FIOMMSGS, &nMessages) } 
FIOFLUSH - Discards all messages in the pipe and releases the 
memory block that contained them 


status = ioctl (fd, FIOFLUSH); 


SEE ALSO 
msgQLib, Programmer's Guide: I/O System 
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NAME 
pipeDrv( ) - initialize the pipe driver 


SYNOPSIS 
STATUS pipeDrv () 


DESCRIPTION 
This routine initializes and installs the driver. It must be called before any 
pipes are created. If INCLUDE_PIPES is defined in configAILh, it is called 


by the root task usrRoott ) in usrConfig.c. 
RETURNS 
| OK, or ERROR if the driver installation fails 
SEE ALSO 
pipeDrv 
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NAME 
pipeDevCreate( ) - create a pipe device 
SYNOPSIS 
STATUS pipeDevCreate (name, nMessages, nBytes) 
char “name; /* name of pipe to be created «/ 
int nMessages; /* max. number of messages in pipe */ 
int nBytes; /* size of each message wf 
DESCRIPTION 


This routine creates a pipe device. It allocates memory for the necessary 
structures and initializes the device. The pipe device will have a maximum 
of nMessages messages of up to nBytes each in the pipe at once. When the 
pipe is full, a task attempting to write to the pipe will be suspended until a 
message has been read. Messages are lost if written to a full pipe at inter- 
rupt level. 


RETURNS 
OK, or ERROR if the call fails. 


SEE ALSO 
pipeDrv 


Rev: 29 Aug 91 | intel 2-2) 


Vx960 5.0 Reference Manual 


oe NUNS 


Lear ees ce s i 
. LER 
ees _ Ne 
RRR ne oF 5 


NAME 
ptyDrv - pe ene driver 


SYNOPSIS 
ptyDrv{ ) - initialize the pasaiasaadial driver 
ptyDevCreate( ) - create a pseudo terminal 


STATUS ptyDrv () 
STATUS ptyDevCreate (name, rdBufSizse, wrtBufsize) 


DESCRIPTION 
The pseudo-terminal driver provides a tty-like interface between a master 
and slave process, typically in network applications. The master process 
simulates the “hardware” side of the driver (e.g.,a USART serial chip), while 
the slave process is the application program that normally talks to the 
driver. 


USER-CALLABLE ROUTINES 
Most of the routines in this driver are accessible only through the I/O sys- 
tem. However, the following routines must be called directly: ptyDrv{ ) to 
initialize the driver, and ptyDevCreate( ) to create devices. 


INITIALIZING THE DRIVER 
Before using the driver, it must be initialized by calling ptyDrv( ). This rou- 
tine must be called before any reads, writes, or calls to ptyDevCreate( ). 
Normally, it is called from usrRoot( ) in usrConfig.c. 


CREATING PSEUDO-TERMINAL DEVICES 
Before a pseudo-terminal can be used, it must be created by calling 
ptyDevCreate( ): 
STATUS ptyDevCreate (name, rdBufsize, wrt BufSize) 
char ‘name; /* name of pseudo terminal */ 
int rdBufSize; /* size of terminal read buffer */ 
int wrtBufSise; /* size of write buffer */ 


For instance, to create the device pair “/pty/0.M”’ and “/pty/0.S”, with 
read and write buffer sizes of 512 bytes, the proper call would be: 


ptyDevCreate ("/pty/0.", 512, 512); 
When ptyDevCreate() is called, two devices are created (the master and 


slave device), one called nameM and the other nameS, which can then be 
opened by the master and slave processes. Data written to the master 
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device can then be read on the slave device, and vice versa. Calls to ioctl( ) 
may be made to either device, but they should only apply to the slave side 
since the master and siave are the same device. 


lIOCTL FUNCTIONS 
Pseudo-terminal drivers respond to the same ioctl() functions used by tty 
devices. These functions are defined in ioLib.h and documented in the 
manual entry for tyLib. 


SEE ALSO 
tyLib, Programmer's Guide: I/O System 
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NAME 
ptyDrv{ ) - initialize the pseudo-terminal driver 


SYNOPSIS 
STATUS ptyDrv () 


DESCRIPTION 
This routine initializes the pseudo-terminal driver. It must be called before 


any other routine in this module. 


SEE ALSO 
ptyDrv 


NAME 


ptyDevCreate( ) - create a pseudo terminal 


SYNOPSIS 
STATUS ptyDevCreate (name, rdBufSise, wrtBufsize) 
char “name; /* name of pseudo terminal «/ 
int rdBufSize; /* size of terminal read buffer */ 
int wrtBufSizse; /* size of write buffer */ 
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DESCRIPTION 


This routine creates a master and slave device which can then be opened by 
the master and slave processes. The master process simulates the 
“hardware” side of the driver, while the slave process is the application pro- 
gram that normally talks to a tty driver. Data written to the master device 
can then be read on the slave device, and vice versa. 


RETURNS 


OK, or ERROR if the routine runs out of memory. 


SEE ALSO 
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NAME 
ramDrv - RAM disk driver 


SYNOPSIS 
ramDrvu{ ) - prepare a RAM disk driver for use (optional) 
ramDevCreate( ) - create a RAM disk device 


STATUS remDrv () 
BLX DEV *ramDevCreate (ramAddr, bytesPerBlk, blksPerTrack, nilocks, blkOffset) 


DESCRIPTION 
This driver emulates a disk driver, but actually keeps all data in memory. 
The memory location and size are specified when the “disk” is created. The 
RAM disk feature is useful when data must be preserved between boots of 
Vx960 or when sharing data between CPUs. 


USER-CALLABLE ROUTINES 
Most of the routines in this driver are accessible only through the I/O sys- 
tem. Two routines, however, can be called directly by the user. The first, 
ramDro ), provides no real function except to parallel the initialization func- 
tion found in true disk device drivers. A call to ramDro{ ) is not required to 
use the RAM disk driver. The second routine, ramDevCreate(), must be 
called directly, however, to create RAM disk devices. 


Once the device has been created, it must be associated with a name and file 
system (DOS, RT-11, or raw disk) by passing the value returned by 
ramDevCreate() — a pointer to a block device structure.-— to: the -file 
system's device initialization routine or make-file-system routine. See the 
manual entry for nenrmenes ) for a more detailed discussion. | 


lOCTL wt 
The RAM driver is called in response. to ioctl\ ) codes-in the same-manner as: .-° : 
anormal disk driver. When the filesystem is unable to handle a specific 
ioctl( ) request, it is passed to the ramDrv driver. Although there is no phy- 
sical device to be controlled, ramDrv does handle a FIODISKFORMAT 
request, which always returns OK. All other ioc#tl() requests return an error 
and set the task's errno to S_ioLib UNKNOWN_REQUEST. | 


SEE ALSO 
dosFsDevInit{ ), dosFsMkfs( ), rt11FsDevInit{ ), rt11FsMkfs( ), 
rawFsDevtInit{ ), Programmer's Guide: I/O System, Local File Systems 
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NAME 
ramDrv{ ) - prepare a RAM disk driver for use (optional) 


SYNOPSIS 
STATUS rasDrv () 


DESCRIPTION 
This routine performs no real function, except to provide compatibility with 
earlier versions of ramDrv and to parallel the initialization function found in 
true disk device drivers. It also is used in usrConfig.c to link in the RAM 
disk driver when building Vx960. Otherwise, there is no need to call this 
routine before using the RAM disk driver. 


RETURNS 
OK, always.: 


SEE ALSO 
ramDrv 


NAME 
ramDevCreate( ) - create a RAM disk device 


SYNOPSIS 


BLK _DEV *ramDevCreate (ramAddr, bytesPerBlk, blksPerTrack, nBlocks, blkOffset) 


char ‘*ramAddr; /* Where it is in memory (0 = malloc) */ 
int bytesPerBlk; /* Mumber of bytes per block */ . 

int blksPerfrack; /* Wumber of blocks per track */ 

int nBlocks; /* Wamber of blocks on this device */ 
int blkOffset; /* Mumber of blocks to skip at 


* beginning of physical device */ 


DESCRIPTION 
This routine creates a RAM disk device. 


Memory for the RAM disk can be pre-allocated separately; if so, the ramAddr 
parameter should be the address of the pre-allocated device memory. Or, 
memory can be automatically allocated with malloc( ) by setting ramAdadr to 
zero. 


The bytesPerBlk parameter specifies the size of each logical block on the 
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RAM disk. If bytesPerBlk is zero, 512 is used. 
The blksPerTrack parameter specifies the number of blocks on each logical 


o*“ 


track of the RAM disk. If blksPerTrack is zero, the count of blocks per track is 
set to nBlocks (i.e., the disk is defined as having only one track). 


The nBlocks parameter specifies the size of the disk, in blocks. If nBlocks is 
zero, a default size is used. The default is calculated using a total disk size 
of either 51,200 bytes or one-half of the size of the largest memory area avail- 
able, whichever is less. This default disk size is then divided by bytesPerBlk 
to determine the number of blocks. 


The blkOffset parameter specifies an offset, in blocks, from the start of the 
device to be used when writing or reading the RAM disk. This offset is 
added to the block numbers passed by the file system during disk accesses. 
(Vx960 file systems always use block numbers beginning at zero for the start 
of a device.) This offset value is typically useful only if a specific address is 
given for ramAddr. Normally, blkOffset is 0. | 


FILE SYSTEMS 
Once the device has been created, it must be associated with a name and a 
file system (DOS, RT-11, or raw disk). This is accomplished using the file 
system's device initialization routine or make-file-system routine, e.g., 
dosFsDevInit( ) or dosFsMkfs{ ). The ramDevCreate( ) call returns a pointer 
to a block device structure (BLK_DEV). This structure contains fields that 
describe the physical properties of a disk device and specify the addresses of 
routines within the ramDrv driver. The BLK_DEV structure address must 
be passed to the desired file system (dosFs, rtl1Fs or rawFs) via the file 
system's device initialization or make-file-system routine. Only then is a 
name and file system associated with the device, making it available for use. 


EXAMPLE 

In the following example, a 200-Kbyte RAM disk is created with automati- 
cally allocated memory, 512-byte blocks, a single track, and no block offset. 
The device is then initialized for use with DOS and assigned the name 
“DEV1:": | 

BLK DEV “pBlkDev; 

DO6_VOL_DESC *pVolDesc; 

palkDev = remDevCreate (0, 512, 400, 400, 0); 

pYolDesc = dosFskkfs ("DEV1:", pBlkDev); 


The dosFsMkfs( ) routine calls dosFsDevInit({ ) with default parameters and 
initializes the file system on the disk by calling ioctl() with the 
FIODISKINIT function. 


If the RAM disk memory already contains a disk image created elsewhere, 
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the first argument to ramDevCreate( ) should be the address in memory, 
and the formatting parameters — bytesPerBlk, blksPerTrack, nBlocks, and 


 blkOffset — must be identicai to those used when the image was created. For 


example: 


pulkDev = ramDevCreate (0xc0000, 512, 400, 400, 0); 
pvolDesc = dosFsDevinit (“DEVi:", pBlkDev, MULL); 


In this case, dosFsDevInit({ ) must be used instead of dosFsMkfs( ), since the 
file system will already exist on the disk and should not be re-initialized. 
This procedure is useful if a RAM disk is to be created at the same address 
used in a previous boot of Vx960. The contents of the RAM disk will then be 
preserved. 


These same procedures apply for creating a RAM disk with RT-11 using 
rt11FsDevInit( ) and rt11FsMkfs( ), or creating a RAM disk with rawFs using 
rawFsDevInit{ ). 


RETURNS 


A pointer to a block device (BLK_DEV) structure, or NULL if memory can- 
not be allocated for the device structure or RAM disk. 


SEE ALSO 
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NAME 
wd33c93Lib - library for the wd33c93 SCSI-Bus Interface Controller (SBIC) 


SYNOPSIS 
wad33c93CtriCreate( ) - create and partially initialize an SBIC structure 
wd33c93CtrlInit{ ) - initialize the user-specified fields in an SBIC structure 
sbicShow( ) - display values of all readable wd33c93 chip registers 


WD_33C93_ SCSI_CTRL *wi33c93CtrlCreate (sbicBaseAdrs, regOffset, clkPeriod, ... 
STATUS wd33c93CtrlInit (pSbic, scsiCtriBusId, defaultSelTimeOut, scsiPriority) 
STATUS sbicShow (pécsiCtrl) 


DESCRIPTION 
This is the I/O driver for the Western Digital wd33c93 SCSI-Bus Interface 
Controller (SBIC). It is designed to work in conjunction with the scsiLib 
library. 

USER CALLABLE ROUTINES 
Most of the routines in this driver are accessible only through the I/O sys- 


tem. Two routines, however, must be called directly: wd33c93CétrlCreate( ) 
to create a controller structure, and wd33c93CtlInit( ) to initialize it. 


INCLUDE FILES 
wd33c93.h 


SEE ALSO 
Programmer's Guide: I/O System 


NAME 


wd33c93CtrlCreate( ) - create and partially initialize an SBIC structure | 


SYNOPSIS 
WD_33C93_SCSI_CTRL *wd33c93CtrlCreate (sbicBaseAdrs, regOffset, clkPeriod, 
sbicScsiReset, sbicDmaBytesIn, 


abicDmaBytesOut ) 
UINTS *sbicBaseAdrs} /* base address of the SBIC */ 
int — regOffset; /* address offset between consecutive regs. */ 
UINT clkPeriod; /* period of the controller clock (nsec) */ 


FUNCPTR sbicScsiReset; /* function to reset SCSI bus */ 
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FUNCPTR sbicDmaBytesIn; /* function for SCSI DMA input */ 
FUNCPTR sbicDmaBytesOut; /* function for SCSI DMA output */ 


DESCRIPTION 
This routine creates an SBIC data structure and must be called before using 
an SBIC chip. It should be called only once for a given SBIC. Since it allo- 
cates memory for a structure needed by all routines in wd33c93Lib, it must 
be called before any other routines in the library. 


After calling this routine, at least one call to wd33c93CtrlInit( ) should be 
made before any SCSI transaction is initiated using the SBIC. 


NOTE: Only the non-multiplexed processor interface is supported. 
A detailed description of the input parameters follows: 
sbicBaseAdrs 
- the address where the CPU would access the lowest (AUX STATUS) 
register of the SBIC. | 
regOffset 


- The address offset (in bytes) to access consecutive registers. (This 
must be a power of 2; for example, 1, 2, 4, etc.) 


clkPeriod 
- the period (in nanoseconds) of the signal-to-SBIC clock input only 
used for select timeouts. 


spcDmaBytesIn and spcDmaBytesOut 
- board-specific routines to handle DMA input and output; if these are 
NULL (0), SBIC program transfer mode is used. DMA is imple- 
mented only during SCSI data in/out phases. The interface to these 
DMaA routines must be of the form: 


STATUS xxDmaBytes{In, Out} (pScsiPhysDev, pBuffer, bufLength) 


SCSI_ PHYS DEV *pScsiPhysDev;/* ptr to phys dev info * 
UINTS “pBuf fer; /* ptr to the data buffer * 
int bufLength; /* number of bytes to xfer * 


RETURNS 
A pointer to the SBIC control structure, or NULL if a is unavailable or 
there are bad parameters. 


SEE ALSO 
wd33c93Lib 
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NAME 
wd33c93CtrlInit{ ) - initialize the user-specified fields in an SBIC structure 
SYNOPSIS 
STATUS wd33c93Ctrlinit (pSbic, scsiCtrlBpusId, defaultSelTimeOut, scsipPriority) 
SBIC ‘*pSbic; /* per to SBIC info */ 
int scsiCtrlBusId; /* @9CB8I bus ID of this sBIC */ 
UINT defaultSelTimeOut; /* default dev. select timeout (microsec) */ 
int scsiPriority; | /* priority of task when doing SCSI I/O */ 
DESCRIPTION 


This routine initializes an SBIC structure, after the structure is created with 
wd33c93CtriCreate( ). This structure must be initialized before the SBIC can 
be used. It may be called more than once if needed; however, it should only 
be called while there is no activity on the SCSI interface. 


Before returning, this routine pulses RST (reset) on the SCSI bus, thus reset- 
ting all attached devices. 


The input parameters are as follows: 


pSbic | 
- a pointer to the WD_33C93 SCSI CTRL structure created with 
wd33c93CtriCreate( ). 


scsiCtrlBuslId : 
- the SCSI bus ID of the SBIC. Its value is somewhat arbitrary: seven 
(7), or highest priority, is conventional. The value must be in the 
range 0 - 7. 


defaultSelTimeOut 
- the timeout (in microseconds) for selecting a SCSI device attached to 
this controller; called “default’’ since the timeout may be specified 
per device (see scsiPhysDevCreate( )). The recommended value zero 
(0) specifies SCSI DEF SELECT TIMEOUT (250 millisec). The max- 
imum timeout possible is approximately 2 seconds. Values over the 
maximum specify the maximum. See the Western Digital documenta- 
tion for more information. 
scsiPriority 
- the priority to which a task is set when performing a SCSI transac- 
tion. Legal priorities are 0 to 255. Alternately, a -1 indicates that the 
priority should not be altered during SCSI transactions. 
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RETURNS 
OK, or ERROR if parameters are out of range. 


SEE ALSO 
wd33c93Lib 
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NAME | 
sbicShow( ) - display values of all readable wd33c93 chip registers 


SYNOPSIS 
STATUS sbicShow (p&csiCtrl) 
SCSI_CTRL ‘*pScsiCtrl; /* ptr to SCSI controller info */ 


DESCRIPTION 
This routine displays the state of the SBIC registers in a user-friendly way. It 
is only used during debugging. 


RETURNS 
OK, or ERROR if the call fails. 


SEE ALSO 
wd33c93Lib 
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compress 
extract 

jump 
makeStatTbl 
makeSymTbl 
makeVersion 
picLib 
vwbug 
vwman 


vxencrypt 
xsym 
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NAME 
compress - general purpose file compression utility 
SYNOPSIS 
compress [-dfFqc] [-b bits] [file ...] 
DESCRIPTION 
This tool reduces the size of a file using the modified Lempel-Ziv method. 
INPUT 
file ... - the files to be compressed. If none are specified, input is 
taken from standard input. 
OUTPUT | 
file.Z - the compressed form of the file(s) with the same mode, 
owner, and times; or standard output if the input was stan- 
dard input. 
OPTIONS 
| -d - decompress instead. 
-C - write output on standard output; do not remove original. 
-b bits - limit the maximum number of bits/code to bits. 
-f - force the output file to be generated, even if one already 
| exists. If -f is not used, the user will be prompted if standard 
input is a tty; otherwise, the output file will not be overwrit- 
ten. 
-F - forces the output file to be generated, even if no space is 
saved by compressing. 
-q - generate no output, unless there is an error. 
ASSUMPTIONS 


When a filename is given, it is replaced with the compressed version (.Z suf- 
fix) only if the file decreased in size. 


ALGORITHM 
The algorithm used is a modified Lempel-Ziv method (LZW) which finds 
common substrings and replaces them with a variable size code. This is 
deterministic, and can be done on the fly. ‘Thus, the decompression pro- 
cedure needs no input table, but tracks the way the table was built. The 
algorithm is from “‘A Technique for High Performance Data Compression,’ 
Terry A. Welch, IEEE Computer, Vol. 17, No. 6 June 1984), pp. 8-19. 
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AUTHOR 
The original compress program was written by: Spencer W. Thomas, Jim 
McKie, Steve Davies, Ken Turkowski, James A. Woods, Joe Orost. 
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NAME 


extract - conditionally extract files from an archive 


SYNOPSIS 
extract [ -v ] archive 


DESCRIPTION 
This tool extracts any files from a specified archive that are not already 
present in the current working directory. File modification times are 
preserved as stored in the archive. 


OPTIONS 
-v - verbose; give a file-by-file description of the extraction of archive 


files. 
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NAME 
jump - show jumpering of target and associated boards 


SYNOPSIS | | 
NO CALLABLE ROUTINES 


SYNOPSIS 
jump [-a] targetDir 


DESCRIPTION 
This tool is a utility to aid users in jumpering VME boards. The pictures 


generated are derived from the parameters in the config.h file of the speci- 


fied target directory. 
OPTIONS | 

-a - output information about all boards for the specified target. 
EXAMPLES 


The following will prompt the user for boards: 


jump ../config/hkv960 


The following will output all boards to the line printer: 
jump -a ../config/hkv960 | lpr 


WARNING 
Not all target CPUs have 100% reliable pictures. Verify with board's 
hardware manual. 

FILES 
vw/bin/picLib.o -- pictures for network boards 
vw/config/cpu/pic_cpu.c - target CPU's picture program 


vw/config/cpu/pic_board.c —_- other board's picture program 
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NAME 


makeStatTbl - make a table of status values 


SYNOPSIS 


makeStatTbl hdir [...] 


DESCRIPTION 


This tool creates an array of type SYMBOL which contains the names and 
values of all the status codes defined in the -h files in the specified 
directory(s). All status codes must be prefixed with “S _” to be included in 
this table, with the exception of status codes in the UNIX-compatible header 
file errno.h. In each hdir there must be a *ModNum.h file which defines the 
module numbers, e.g., ““M_’’. The generated code is written to standard out- 
put. | 


The symbol array is accessible through the global variable statTbl. The array 
contains statTblSize elements. These are the only external declarations in the 
generated code. 


This tool’s primary use is for creating the Vx960 status table used by 
printErrno( ), but may be used by applications as well. For an example, see 
vw/config/all/statTbl.c, which is generated by this tool from vw/h/*. 


FILES 
hdir/*ModNum.h = - module number file for each h a 
symLib.h - symbol header file 

SEE ALSO 


errnoLib, symLib 
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NAME 
makeSymiIbl - make a table of symbols 


SYNOPSIS 
makeSymTbl objMod 


DESCRIPTION 
This tool creates the C code for a symbol table structure containing the 
names, addresses, and types of all global symbols in the specified object 
module; the generated code is written to standard output. usrRoot() in 
usrConfig.c inserts these symbols in the standAloneSymTbl using 
symAddSymbol( ). | 


This tool is used only when creating a stand-alone system. Normally, it is 
not needed, since the symbol table is constructed by reading and interpret- 
ing the symbol table contained in the system load module (b.out or format), 
either from the local boot disk or from a host system over the network. 


The generated symbol table-is:an array of type:SYMBOL accessible through 
the global variable standTbl. The array contains standTblSize elements. 
These are the only external declarations in the generated code. 


For an example, see the file vw/config/cpu/symTbl.c, which is generated by 
this tool for vxWorks.st in the same directory. 


FILES 
symLib.h - symbol table header file | 
b_out.h - UNIX GNU /960 object module header file 
SEE ALSO a 


xsym 


(ses 
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NAME 
makeVersion - create the Vx960 version module 


SYNOPSIS 
makeVersion 


DESCRIPTION 
This tool creates the source code for a version.c module, which gets linked 
with every Vx960 system for identification. This module contains the sys- 
tem version number and creation date in strings. The generated code is 
written to standard output. 
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NAME 
picLib - jump program support routines 


DESCRIPTION 
This module contains the primitives required to show board jumpering with 
the jump tool. The following routines can be used in drawBoard{ ), defined 
in the target-specific pic_cpu.c. 
VOID printaAt (pic, x, y, string) 
VOID jumperAt (pic, x, y, len, orient, type, contents) 


Parameters: 
pic - array holding the picture. 
x - x coordinate, character position 2 - 78. 
y - y coordinate, line position 1 - 20. 
string - message to display in picture. 
len - number of jumpers in the block. 
orient - orientation of the jumper block: 
HORIZONTAL = =LSBof contents is rightmost jumper. 
VERTICAL = LSB of contents is bottom jumper. 
type - type of individual jumpers in the jumper block: 
HORIZONTAL: 0 = removed, 1 = installed 
VERTICAL: 0 = removed, | = installed 
HORIZONTAL _3: 0 = right, 1 = left 
VERTICAL 3: 0 = down, 1 = up 
contents - configuration of the jumpers in the jumper block. 
INCLUDE FILE 
picLib.h 
SEE ALSO 


jump, vw/config/target/pic_cpu.c 
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NAME 
vwbug - submit a Technical Support Request (TSR) to Intel 


SYNOPSIS 
_ vwbug [-0 outfile] [rectpients] 


DESCRIPTION 
This tool creates a software error report and mails it to 
uunetlichips!vx960bug. The user is placed in the editor with a Technical Sup- 
port Request (TSR) template. The report is mailed automatically when the 
user exits the editor. 


OPTIONS 
-o outfile - the report is saved in outfile for printing. 
recipients - additional copies of the report are mailed to the speci- 
fied recipients. 
CAVEAT 


A mail path to uunet must exist if the report is to be successfully routed to 
Intel. The script can be edited to set the appropriate mail path. 


ENVIRONMENT 
vwbug uses the editor specified by the environment variables VISUAL or 
EDITOR if they are set, otherwise it uses vi. 
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NAME 
vwmian - print Vx960 manual entries 


SYNOPSIS 
vwmian [section] [-1] [-t] entry 


DESCRIPTION 
This tool looks up and displays an entry in the on-line Vx960 reference 
manual. With no options, it finds and displays entry. If it cannot find a for- 
matted version of the entry in the vw/man directory, it formats and displays 
the nroff source copy from vw/mansrec, and, if write restrictions permit, adds 
a formatted version to vw/man. 


OPTIONS 

-l - List all entries which include the string entry. 

section - Confine the search to a particular section: 1, 2, 3, 4, or t. 

-t - Send troff-formatted entry to printer. The default troff for- 
matter is nroff. The vwman script can be edited to accommo- 
date other versions. 

EXAMPLES 


List all entries whose names include the string “log’’: 
% wanan -l log 


Display hkv960 target information: 
% vwman hkv960/target 


Display and print a troff version of the netDrv:entry:from:Section 2: 


t vwaan 2 -t netDrv 


NOTE si 
The files tmac.ref and tmac.angen may need to be installed in usr/lib/tmac 
for this to work. | | 

FILES 
vw/mansrc/man{1,2,3,4,t} - source manual entries 
vw/man/man{1,2,3,4,0} - nroffed manual entries 


vw/mansrc/include/tmac/tmac.angen —_- nroff/troff macros 
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NAME 

vxencrypt - encryption program for loginLib 
SYNOPSIS 

vxencrypt 


DESCRIPTION 
This tool generates the encrypted equivalent of a supplied password. It 
prompts the user to enter a password, and then displays the encrypted ver- 
sion. 


The encrypted password should then be supplied to Vx960 using the 
loginUserAdd{) routine. This is only necessary if you have enabled login 
security by defining INCLUDE_SECURITY in configAILh. For more infor- 
mation, see the manual entry for loginLib. 


This tool contains the default encryption routine used _ in 
loginDefaultEncrypt(). If the default ,encryption:-routine: is. replaced in 
Vx960, the routine in this module should also be replaced to reflect the 
changes in the encryption algorithm. 

SEE ALSO 
loginLib, Programmer's Guide: Shell 
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NAME 

xsym - extract the symbol table from an object module 
SYNOPSIS 

xsym < objMod > symTbl 
DESCRIPTION 


This tool reads an object module on standard input, and writes an object 
module on standard output. The output object module contains only the 
symbol table, with no code, but is otherwise a normal, executable object 
module. 


This tool is used to generate the Vx960 symbol table, vxWorks.sym. 


FILES | 
| b_out.h - GNU/960 bout.h object module header file 


SEE ALSO 
makeSymTbl, GNU/960 b.out and coff documentation 
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partition on SCSI block device. define logical 2 .ienssssee scsiBlkDevCreate{ ) 
command to SCSI device. issue TEST_UNIT_READY ... scsiTestUnitRdy{ ) 

FORMAT _ UNIT command to SCSI device. iSSUe ns eeessccssosesconsevessossonessoonsensssoes scsiFormatunit{ ) 
issue INQUIRY Command to SCSI device. 2... cccensccccccncsssescssssseecesecesscecesececeesrenssesececesseveee scsilnquiry ) 
MODE SELECT command to SCSI device. iSSue ...essssssssssnsnnsseesenseseesscosesseeeeess scsiModeSelect ) 
MODE SENSE comumand to SCSI device. iSSue ......scsccosssseccsenessornecssenesonesscensee scsiModeSense{ ) 
Tead Sectors from SCSI DICK EVIE. on. cnsccnnsesnnessnnsnnsssnssnnsnsensscsescnsensnenessceessesseneess scsiRdSecs( ) 
READ CAPACITY command to SCSI device. iSSte .ssssssssssssssssccscccescorsneseconssces scsiReadCapacity{ ) 
Write Sectors (0 SCSI hock Revie. anne enee nen eseeenccsceeeeneeseneneeeserenntene scsiWrtSecs( ) 
underlying driver is tty device. retuum whether ......sssssssssssnessereesssesnees .... isatty{ ) 

do task-level write for thy Device. .ss.csscsssscceseeessescessscensenssnnecsensseseunnteeesseesnnmneccss tyWrite( ) 

do task-level read for thy GeVICE. ssssersessseesssnsennssennsereeeeesseesssessenrennmeseeeremneenene LYRE AA ) 

file system On Dhock device. imitialiZe ne ssccsssnscscssccececessnnsssesssesneesesss diskInit{ ) 

Create remote file GeVICE. ....ccssecssesessscessrssccsseersssssesrereseeeeesessesseeese MELDEVCreate{ ) 

TAMOUIIM NES evi e  escissscsasesieccttee cctsces tees bsesconecieslaanteicgcsees nfsUnmount{ ) 

CHALE PIPe OV ICS. asses sssssich css hscatsascscasdencessdescecseeasianstas pipeDevCreate{ ) 

Create RAM disk GevVice. ....ne-vssecsssssunmssnsssssersssoesocssnseseeesssccsoorees ramDevCreate{ ) 

ee TOALE TIVERONY  CEVIC ES ssi tcclascce i tae taeaaearncass memDevCreate{ ) 
on | system. initialize device and create GOSFS fC i ecscceneceeeee dosFsMifs\ ) 
system. initialize device and create RT-11 file 2 ennecnes rt11FsMks( ). 

issue REQUEST SENSE command to device and read results, .sessen-suesinnnnn SCStREGSENSE ) 
handle device comtrol requests. wn seasesnessssscesseeeennsceseneten tyloctl( ) 

Initialize RT-11 device Aescriptor .---..scsssecssecesssssssensseesneeeeene rt11FsDevInit{ ) 

Initialize thy Cevice GESCrIPHOL. ...ceensscsssccssseneuensseeeessccescoseensenene tyDevInit{ ) 

pseudo memory Pevice AVL. ...c....succnennennecnieneenennssserseseescensneseente memDrv 

extract backplane address from device fied. ...........scsssessessseennees DOOTBpAnchorExtract{ ) 

raw block device file system Hbrary, ...sscssssecesssseceseeneees rawFsLib 

delete device from I/O system. ....ssssseessneeenee iosDevDelete( ) 

find 1/O device in device Hist. 2. escsssceneeeeesenees 10S DeUF ind ) 
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find I/O device in Device Hist. es ccsssseensensnensssensnnssesneessenernecnscrenesneess KOS DEUF INA ) 

create SCSI physical device Structure. .asanssenseoeeeereeneee SCSIP hrys DevCreate{ ) 

delete SCSI physical device Structure. enenecenenene. 5CSIPRYSDevDelete{ ) 

pointer to SCSI physical device structure. retum ..................... scsiPhysDevidGet( ) 

add device t01/O SyStem. .u........eecsenennneeee SOSDEVARE ) 

modify mode Of raAW Gevice VONUMNC. nn neeeseneeeeeeeeeennseneeeeeeee NW EsModeChange( ) 

disable raw Gevice VOLUME. ...nnssceenensecrconseererseeens PAW FsVolUnnount, ) 

functions. associate block device with dosFs file system ...........-........ dosFsDevinsit{ ) 

functions. associate block device with raw VOM .......-00... MW FsDevinit( ) 

Fist all system -KrVOWwn =eVACCS, aansaanscnssenesscsrsssesescrernenneerne deve ) 

display mounted NFS devices. .-senscsesscessseesesesessemessntenuansetnnsesseensees nfsDevShow( ) 

to boot ROMs. reset network devices and transfer COMO ...eeecx-vececnecescecsceessceesees ) 

controller. list physical devices attached t0 SCSI nnsesssessssceesserseeeesmeeeees scsiShouX ) 

controller. configure all devices connected £0 SCS n-ne. SCSAMBOCON IGS ) 

display list of Gevices in SYStEM. -..--secessccsseesseseeeeeseeeeee tosDevShouX ) 

Tea Ome ervey frm GAO CHONY. ena nseessssssesecseccnsensnceeeccennccnsneneeccscceseennnnnene readdir( ) 

Teset Position tO start Of CEECEOIY. ....-u-vsscccoscccsscesesenceereeeercenenseneeeeseeseeesseeee rewinadir( ) 

GIOCORY, Seeger ee eae closedir{ ) 

Chnarngee etal ive Che yy sccccascsasscasssscssaesancsnsscodsanecesanisondsntesesadsScnasceeotsnniens cd) 

Print current default TECHOY. .n.sascccscccsccecserssesweccesecesseesnmnssccsceessensnmmneceeseeesene pwd) 

Vist Ome IES CF CRMC CE ON Yast assassin cascimnnentsss cbc sencnteenabnctnnels Is() 

contents of RT-11, ftp, or rsh ireCtOry. Tt ....e.sessscssessnsensceecsceeseeeesseennessunneeeereceeseeeeeees IsOld ) 

MAKE CWOCORY ction sc tdcocianiateemenlanien mkdir( ) 

TOMNOV EC AICRONY sae stele aed artes liacaceeatlediaes rmdir( ) 

do long listing of directory COMMEMES. ...nnennsscccosecscccsessssnneceseceeeceeseeesennseenscesees 1K ) 

Open directory fOr SeArCharyg. n..aenscsecsseensevecceseereneeseeeeseenee opendir( ) 

POSIX directory ENN REAR Ys sia cise tcerccoreccnio wees GitLib 

specified number of / disassemble and disphay 2. .sccscssenvsssscsecscccsesernneseeccees K) 

disassemble 1960 object COG... .n..eesesnewvsecssccees dsm960Inst{ ) 

Vx960 / 80960 disassemn ber. e.aeesesaaecssseccssccescessrmnmessssescecsecssnensee dsm960Lib 

format Gisk: oso ee diskFormat{ ) 

Create RAM isk Gevice. cscs nccssssensscccnsenssscsecsesennsecsecsenseeee ramDevCreate{ ) 

RAM  lisk Graver. ..cssssssscseonecsseensssecsereesersssersennecssemnececsemneeee FMD TV 

(optional). prepare RAM isk driver fOr USC q....-seecvsenseessesssscesssrssecseeeseeeeeeen ramDro\ ) 

initialize device and create oOsFs file system. ..sescccsssccssessesessssseneeetee dosFsMKfs< ) 

associate block device with dosFs file system functions. ..........cssesee dosFsDevInit{ ) 

Prepare to USE HOSES Ary. an eeeaeensvvecensccesseeeceessnnmseneneenseeescnenrentee dosFsInit{ ) 

Modify mode Of GOSFS VOLUME. ..ncvseeeeesenceeensersseeseesen dosFsModeChangel ) 

UNM OUNE OSES VOR. nc aieanscsnnennsnanescseressccnseseeree dosFsVolUnmount{ ) 

structure. initialize dosFs volume configuration ............. dosFsConfiginit{ ) 

Vi960 Se SunOS backplarve Graver. nsec neencsssesssensccessecessecenseseseeneccnsceneenesennesnnnecsscces cent if bp 
ENP 10/L Ethernet interface river. CMC 2...-sss--ssssssossssccsscesscossemssssneeneersceeseeeeeeeseeeeeee if 

201 /202,/302 Ethernet interface driver. Exccelar EXOS 2 saascscsccssccceesssssessesesssenecesecenee if ex 

LANCE Ethernet interface river. ..sssscseennseonennsecncerseeccessesensennececenscesesqueseecenneenenten if In 
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IP (SLIP) network interface driver. serial lime 2... a--ssscscccccserscrsrsrenrssemoeoeresne Hf 8 1-134 
Hstall T/O raver. cans nscssssscssnnrensesnsesnnncecsssersssccressesnemeee SOSDrvIustall ) 1-173 

TEMOVE T/O GeV er. sn anannsccscnneeeseseessencreanssamriernecreccesssoes SOSDrpRespove ) 1-174 

install network remote file GAVEL. on. eansesssssscnsovevessessessansesscsssscrsnncsnnsssessnarecessessesennee MEEDYU) 2-10 
Network File System 1/O  Griver. s.s.ssssssssssssosssecssnarsossseereeresesrreenscnsernsnsnnarsameeerseerenseeee MBDrv 2-12 


Emestall NFS river. sanwosssescscousenssseceorseseeereeeerensenstessnarersseseseereeeceene MSD) 2-14 
PIPE T/O  AIVET. .nenseeesserseerrenereereerreneeneereemrereerereerreereerrenrereeeee PipeDrv 2-18 
Initialize pipe NAVE. a aesenncssssoneceecesosseenersssnreeseerenreoreervensnescrcnrsesesens PAPECDV) 2-20 
pseudo-termrimal river. ....-ssssvswssasesssenmnseneseennssesseoremncsrencenmmannnernnneeee PAYDIV 2-22 
IMitialize pseudo-terminal VET. —..cseevvseerneceseeersmrenenrerseorseeneeneeenernmnssnseenneen PAYDVA ) 2-23 
RAM, Ghisk: hie secs cca tea ramDry 2-25 
psetido memory device GIVET. n.n..nscccssccseccssecsseessennunnsmnnsnisssesecneceescenseeeceeesseete memDryv 2-5 
Install memory ALIVE. ....nesessesssnsecwssennenssvsssnenscnsvannacecencoesseeereesseenseeesee memDro{ a 2-6 
Network remote file T/O riven, .-.-.-ssssscscssesssscssecsssenseenseeenssensneunennssssnesnneccecceeeseeasenee 2-8 
prepare RAM disk driver for use (Optional). n-..-..-cscsessscessseresssessnee ener 2-26 
return whether underlying iriver is tty Gevice. .....csscccscccssseseecseceescecessesnnesseessees  isatty() 1-371 
tty driver Support LDTALY. .isereescoesenreecseenrnesenetsememenenenn CYLID 1-461 
display list of system YIVETS.. ...n..--sescscccsecsssensensneeeseennneneecenes teen tjosDrvShou{) 1-174 
Jogin Lib. encryption program fOL ...eccsscnsscsseeessnnenenseeeseee vxencrypt 311 
Install encryption TOULIE. .......--scccscccscccseeeee loginEncryptinstall) 1-204 
default password encryption routine... eecseccsccessees loginDefaultEncrypt{) 1-205 
Change encd-of-file Character, ....cssccssssseeesserseeesensseeseees tyEOFSet{) 1-469 
determine if end-of-file has been read... esscsesssecssennerescsscsnneeneeeee FEO) 1-386 
reset error and end-of-file ivGicatOrs, esescacscscnseceencseemereeeesevesscnsensee clearer) 1-385 
driver. CMC ENP 10/L Ethernet interface .....ncavscssscccseccssee if enp 1-130 
attach enp interface to NEtWOTK. ..n.ssnneccseeesereseeesnn Cntpattachh) 1-130 
probe addiress fOr DUS OLTOT. ...esecsssssseessessnssssrssessaseescecesecseseeenenscceeeesessee vxMemProbe{) 1-513 
formatted string to standard e1rOr. Print ...-seccsosenssseesecssecseeecseeeseccessnssnsssnnsneensces printEr() 1-83 
Indicators. reset error ard C1Vd-OF-FMe! ssesecscsescssenereeesscnsereesennnscoes clearerr() 1-385 
reading or/ determine if error has Occurred Whi nn. ..sssscsasesssescosesseereereennnenne ferror() 1-386 
log formatted error MESSAGE. .n.nssesscssscuesensninniossesesenessageccssoossesconees logMsq{) 1-194. 
error status library. ...2.:.smSisiis Se. ..enmoLib. 1-63--. 5... 
< print definition of specified " error status Vale. -eenennniseenncnnnen PINtEN MA) 1-509 
| task. get error status value of calling. wcesienwsnscrenneeee errmoGeH ) 1-65 
task. set error status value Of calling sinner CFMOSEH ) = 1-66 
specified task. get error status Vabite Of .ssssesccscensese ween, CrMOOFlaskGet{) 1-65 
specified task. set error status valite Of wn ssssssessnesseeenee CFMOOfTaskSet{) 1-66 
Internet address. resolve Ghia alidseiaioe choc: case tect etherAddrResolve{) 1-72 
add routine to receive all Ethernet input packets. —............. etherInputHookAdd) 1-70 
send packet on Ethernet irtber face. ...snsanssssssseesseeseecsenesesnsenee CfrerOutput{) 1-69 
CMC ENP 10/L Ethernet interface Giver. ...sssscscsssscccsesseesses if enp 1-130 
~ _Excelan EXOS 201/202/302 Ethernet interface driver. .-s.seuecseeeeseeeereenmmmnnnen tf ex 1-131 
LANCE Ethernet interface Griver. a nensse-cccscccsessneeeeseens ifn 1-132 


add routine to receive all Ethernet output packets. ether OutputtiookAda 1-71 
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hooks. Ethernet raw I/O routines and .......................... etherLib 

Ethernet interface driver. Excelan EXOS 201/202/302 ........... STAC OREEaT Oe Ee if ex 
exc Hos handling facilitice en sik tie awal 

architecture-dependent Trani g: 1960. nasassennsonssecrsenereeerenernees CXCIEOLID 

enitial sown hand; aes 


display exception information... exclfoShow ) 


initialize exception/ interrupt Vectors. ---......000.. ExcVecInit{ ) 

routine to be called with exceptions. Specify ceeannecnenneeenrennenne CXCHOOKAAM ) 
Handle task-level ex ceptioses., n..nsssssssscccsssanssssssecsscecseeeecsenseceeseececeseeenseees CXC TASHA ) 

Oral CASI seascapes ean kad exIel ) 

interface driver. Excelan EXOS 201 / 202/302 Ethverrnet ......seccscuteveoeeseteseestesesssston if ex 
mount all file systems exported by specified NOSt. exeesennensen nfsMountAlk ) 
remote host. display exported file systems Of wc0cccnneunn MfsExportShour ) 

A Logging Fh ann seannnsneevsesneseerenesesenseeneeeeeneenenninenneneneenen logFdAdd{ ) 

set primary logging £0. enone tenet logFdSet{ ) 
helt Menge tna dsc ccesensatbancasestas cha bosonssnnces logFdDelete{ ) 

associate Streain WIEN fC csi sssceccs cheetahs fdoper ) 
formatted string to specified fd. prrimat a. .asssssssccsscssssssnenssceesscecesceseeceececcenseseneeee fdprintfi ) 
argument list to specified fd. /string with Variable a. ccsecessssseseeesssneen ufdprintfi ) 
value. validate open fd and return Criver-Specific ......sscscseeene tosFdValue( ) 

get fd associated with stream. ...sassssssccceerssmenecssene fileno( ) 

in/out/error. get fd for global stardard .eenennsesnseeee ioGlobalStdGet{ ) 

_ in/out/error. set fd for global standard —.......- toGlobalStdSet{ ) 
in/out/error. get fd for task stardard 2... eccesesssnssesnssesscsesesseeeeee toTaskStdGet{ ) 
in/out/error. set fd for task stamdard a -s-sssscosscsscnsennneee SOT ASKStAS et ) 

display list of fd names in system. Sistas vas haaneccataces tosFdShow ) 

PICTIG OT SOE OF FAS iia ga csescsstacantecceencetcenucie Secseastccesets sca taninren cadets select( ) 

default input/output/error fds. set shells a ..sscsesseenrenneeeeceeeeeeee SHEUOrIgStAS eK ) 
CRAG TS sascha ceres ec rast easy te seeaecslataateele aes creat{ ) 

oF 1 ap | "ER ae eae OONSNOET ne POET sessssedGaitcintidenecwenionne Allete{ ) 

delet LC. ee caaeseseensecosseeeerereerserernenenensemanemeretitinb sl ia envienstinn UMTiNI, ) 

pee AU ie eee open ) 

CMOS G* SIS ise esters ei ee CIOL) 

Charge mame Of fhe. a csssnsenssessosecsscocerecesenssenencnrsenenombescoreeseeeerenneemnemeens PENANG ) 

Wie bytes $0 fibe. annsscssesnsernssesonseseeesccnstnessnnssnesoncetnnensenssessceeereeesensseeets UH ) 

empty stream buffers ard Chose fhe... ssssssssssstspsseecececssseeceeeeeeeneceseenseieneinninenseescneeeeseensnat fclose{ ) 
@peern Simmenrny Conn: Fae scsi cassie rcctcsseecardacisaesistanecessac da taeaote tes .. fopern ) 

POUUNOVE: $0 iin hoses teers oneal ceas seeds rn ) 

TAL Strang Savon: Fae as casas cl cents .... fioRdString{ ) 

general purpose file cOMpressiOn Utility. —.-..-eeenseccscccessenseneees compress 

Create remote file Mevice. nn eecennscscsssnsseesceneceesessveeesesereeee netDevCreate{ ) 

iIMstall network remote fake ATV ET. assesses sens neeeenneccen sens eeencenteceneneessentee netDrv{ ) 
substitute named _ file in place of open Stream. sans freopen{ ) 
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network remote file 1/O Chriver. .........csss-<cosccsscsesssseercerseseterssnssseeneeaseseeeseeese CED IV 
Tread bytes from fille Or Device. nscsnscscsssnnsssssssnsercensssenssevesseesseesrerrsenssecsscsssersveees TOGMA ) 


get file status information eee eanenneeeeeereeseeseereenm ene SSE AL ) 

pathname. get file status information USING q.-cesee-vescereeerseeseneee SEAL ) 
device and create RT-11 file system. initialize. .-seomseesenseeeeeenee PELIFSMIYS( ) 
device and create dosFs file system. initialize —....--..ucssscseonseneens AOSFSMIGS{ ) 


Mount NFS file System. .ennsssnssussconsensessseruseeeseereererneseneecsseene PSMoount{ ) 

/block device with dosFs file system fUn HONS. 2 natanesensensesennenees GOSFSDevinit{ ) 
Network File System 1/O driver, ..--s-esss-eesereseseeceneenseeneenre: 65Drv 

Network File System library. .------------e--v-scsesesescsseescewseesessretenmnees nfsLib 

Taw block device file system Hibrary. ...cessssssccssccscseesensennesnesseeesceee rawFsLib 

RT-11 media-compatible file system Wbrary. .......-...-ccssueecssseesseeenneesmneeeen MELIFSLID 
MS-DOS media-compatible file system lbbrary. ..nasievvecseccscecescceseessensseeessenee dosFsLib 
initialize file system Om DOCK Gevice. seeesesssecscscnscceeseeseceseeee ) 

specified host. mount all file systems exported Dy ...........ssccssecsenssessees nfsMountAlk ) 
display exported file systems of remote NOSE. ..eens---sescsosee nfsExportShouX ) 

library. ARPA File Transfer Protocol ...s-ssssssessscsuseescsescensensssnnnenetsnt ftpLib 

ARPA File Transfer Protocol server. .-....cssssscccsesesseseeesesess ftpdLib 

scamning library. floating-point formatting ard ...sscsseesecssecesesssssen floatLib 

initialize floating-point 1/O SUppoOwt --.esseesessessnsneccarsessees floatinit( ) 

task TCB. get floating-point registers ffOM ..W.-...-.. foplaskRegsGet{ ) 

task display floating-point registers of ............. fppTaskRegsShou ) 

task set floating-point registers of ................ fppTaskRegsSet{ ) 
probe for presence of floating-point SUppPoOrt. .nncsccscccscccosenseseeresesete fppProbe( ) 
assembly language routines. floating-point Support ....scscsccesssesccssccoussssececsccensesee fppALib 
library. Ree Sagat en ota teh RIE SP SUT Creer fppLib 
ascccsseesensssesssetnesessreessonsssnsscesecsseenennsseees GSkFormatt ) 

convert cacaaee, ata i oe Sas cae csateas cas fioFormatv( ) 
formatted error MeSSAQR. .eeeesseesceeesssseeeseeeseecserneeeene logMsgX ) 

formatted I/O brary. sssssevsssossssscssceesscnrcsseossscesscnesee fioLib 

| buffer. put formatted string in specified, ..........-cssccusssncsecseseeeen sprintf ) 
a: fd. print formatted string to Specified ..s.ssccssnsccssecesesee fdprintfi ) 
error. print formatted string to starwdard ..eeseesnscseeeneeesscee printEr( ) 
out. print formatted string to stareard ....scssseneesscccceesenesnee printf ) 

Print formatted string t0 SHCA. nn eseeeseenssesecnwececccceseessees fprinth{ ) 

argument listin/ put formatted string with variable 2. vsprintf{ ) 
argument list to/ print formatted string with variable ufdprintfl ) 
argument list to/ print formatted string with variable a ..-.cssccsee uprinth{ ) 
library. floating-point formatting and scanning a eR floatLib 
IMitiate tramsfer Via FTP. see ovsccscseescscccscrsssscsonsseeves cceseenteneneces awweeeees fo Xfer( ) 

send FTP command and get reply. ........ ftpCommand ) 

get FIP command reply. ceccecesecesevvreccssssseseseees we ) 

Initialize FTP data, COmme tine. nnn nnnscscesonsseseen ftpDataConnInit( ) 
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get completed FTP data connection. —....W.......... fipDataConnGet{ ) 

list contents of RT-11, ftp, on rly dine CtOry. a annsesseneanccvseeeseeesnessesserssnsersesenees OLA ) 
Jog in to remote FIP server... ees aeansneenescereeneseeeeemneeeees fl Logie ) 

FTP server daemon tack, n..sssssscseesssesennenneennene fipdTask{ ) 

get control connection to FTP server on specified host. ................... fipHookiy ) 
clean up and finalize FTP server tase, 2acsensssseecsnseessennnenennee fipdDelete{ ) 
iMitialize FTP server task. 2 nsssssssccseccsssersesssemmnnnnsemnerers fipdlnit{ ) 

Controller (SPC) Library. Fujitsu mb87030 SCSI Protocol ...................... mb87030Lib 
| get fdfor global standard in/out/ertor. q............. loGlobalStdGet{ ) 
set fd for global standard in/out/entr. .............. loGlobalStdSet{ ) 

Fist global Sym Dds, a neanssnencscssscascecssenssonsnnnnnnnneensesccs Thigh ) 

SEE TOT MOC ON cs sess a setyntpy ) 


PeTFOLM MOM AOCAL BOO. nan enenvnennnsnrneesenensenecnersent eens cennennsecessenssseenenneeenssses LOMNQTINGA ) 
connect C routine to hardware imberrupt. a eeemnnsocseeeeemneneee BE Connect{ ) 


display NFS Wekp menu .ncscncensncscncenssecesssensennnscscsssccseensssssennecess nfsHely ) 

display debugging Help men ccsccsnea-evnneeesssseeeeeseeeestesenee .. dogHely ) 
display task monitoring Wel MENU. ......seeceenvsssnececsensseesenscereneesnnnenssssnessnetenstsie spyHely ) 
isplay (or set) Shell WistOry. ie eecesnecssecssnsennssenennesssecesseensssesenennenee SHEUAistoryl ) 
Gisplay (or set) Shell WistOry. ......sscscssnnecoasnnnssnneccnenessssssensseeeecessecessnuseneesceesesee h() 
CASK TOOK BOTA «esses cscs ca cicataeensortnbesasticinbonasi taskHookLib 


Ethernet raw I/O routines and NOOKS. ...ccccccscuscccsssscsssseersscoscesesesesecesesessaseresenseeesnneeswsersemrene COHCTLID 


to FTP server on specified host. get comtrol CONMECHHON 2. nnessssnensscecseeeee ftpHookaggK ) 
file systems of remote host. display exported, .....--sssscscesseeese nfsExportShouX ) 

Mg mh Go TOTS OSE sesh Sessa cocemscicieatacccnesehanaciceacs eleatnade ..... rlogi+ ) 

systems exported by specified host. mount all file. e-sessscsseerneesesneen 19f5MountAlk ) 

tables. display host and network routing, .....anscsscsesecesenren routeShou ) 

long (32 bit) from network to host byte order... CONVERT E a ansessseecseemneeenneeeneeeecee ntohl{ ) 

short (16 bit) from network to host byte Order. COMVERE .naseeeenncssssonescnsesecseeenenrecens ntohs( ) 

delete host from host table. 2a nesses hostDelete{) 1 

address. lookup host in host table by Intemet ............. hostGetByAdadr( ) 

lookup host in host table by name. ......... hostGetByName{ ) 

address from network and host numbers. form Intemet .................- inet_makeaddr( ) 

address from network and host numbers. form Intermet ............... inet_makeaddr_b( ) 

AA Tost to host tale. a nensssccsssseneensacecnssecscnnsenseenensensseescs hostAdd ) 

Initialize network host tabbe. nn sssssssuneccccneseescesecsesensessnssennsenenenene hostTbUnit{ ) 

Gelete host from. Wost tab ben, seen sssens sssecisensnccerenedonnessonssneseenses hostDelete( ) 

Risplary: Tucst tellers scctsssncnsSonccasosancassuetzabacenee hostShouw ) 

address. look up host in host table by Intermet ..a--sssssssseseene hostGetByAdar{ ) 

look up host in host table by mame... 1. nsa-cssscseccsssesecesee hostGetByName{ ) 

host table subroutine library... nsssessceeenne hostLib 

Add host to host table. esses essesessessecrseerseeeen ene hostAdd{ ) 

convert long (32 bit) from. host to network byte Oren. saan enen eens htonk ) 

convert short (16 bit) from host to network byte order. ene htons{ ) 
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isplay statistics fOr FOMP. ..s.-eunessccccersseneeseesusmeessersenreonneannnee SCHEDSEASHOUN ) 
get file starters ifr atk ana sassceesccececescenresnsneenenmeers SEAL ) 


Priret Vx960 version, iO eatn n,n eneeeeceseceaseceeeerssccseseeserenescennsssssssens DEYSIONA ) 


print complete information from task’s TB, .--sscscsecsseeeseseeeeeseeeeeee FM ) 

get file status information using pathname. ..-..scccscesesreseeeeeeee stat{ ) 
BETNCTIC ROM = imittiabi zation, nn nasnssscccecsccsermsoonsccsennescceccenessenecccccs romStart{ ) 
ROM. initialization module. ............sccnsesreseeeneneeneneees DOOHNIt 

user-defined system initialization routine... enscccsnsssecsescccsennnceeseesen usrinit( ) 
initialize backgplame AMC. ..s.nesessnncseccecececeesssessneeseens bpInit( ) 

create and initialize binary semaphore. .....--secsenseneeee semBCreate( ) 

for mb87030 SPC. initialize control structure ........................ mb87030C irilnit( ) 
create and initialize counting Semaphore. eve sentCCreate( ) 
IMitialize debug Package. ....-n-ecsscceseeeeerssenessceesseeee dbglnit( ) 

dosFs file system. initialize device ard Create. .cssseseeseoon dosFsMkfs( ) 
RT-11 file system. initialize device and create on ennsnsssccseeesens rt11FsMiys( ) 
configuration structure. initialize dosFs VOW e 220.......---.000 ... dosFsConfiginit{ ) 
package. initialize exception nardhing ne eeeesseeececseccecseeseesen excInit( ) 

vectors. initialize exception / iberrupt ...--.-...scecccseceessen excVecInit{ ) 

logical partition. initialize fields i SCSI on asnnvsncvssccesssenes scsiBlkDevinit{ ) 
block device. initialize file System O11 ..eesesssvewsescsssocscccsssessesneosssees diskInit{ ) 
support. initialize floating-point 1/O ...eeesereesnnenecsscereseee floatinit{ ) 
connection. initialize FTP data pas Saastoestececieaces ftpDataConnInit{ ) 


1s 


semaphore. create and initialize mutual-exclusion near oenenen SOM ICrecitel ) 1 
| inidalize networkchoet table... howtTWlintit} 

initialize NetWOrK Package. .eeenceessseneeeseesnsen netLibInit( )— 
routines. initialize met work SHOW ..csessenssscsc-vesscsecesssoseee netShowInit{ ) 
IMitialize PIP! GATIVET. .vnssscssseccservececseeescsessneesceeeeee pipeDro{ ) 
driver. initialize pseudo-termiimall ..s.neseneenntenrsseeseeeee ptyDr ) 
facility initialize remote login ... Siete oceans rlogInit( ) 
IMitialize RPC Package. ..scsccsecesesceesscsesceesseseeenneenssee rpclnit{ ) 
descriptor. initialize RT-11 device a .sscseseennnne t11FsDevInit{ ) 
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create and partially initialize SBIC structure. .............. WASICISCHICreate() 2-29 


initialize select{ ) library. —......................... Selectinit{ ) 1-314 
list. initialize e select{ )wake-up Jessica selWakeupListinit{ ) 1-317 


. initialize task variables 2.2... baskVarInit{ ) 1-439 
specified address. initialize task with stack at 2 w-vnaennees fasklnit{ ) 1-420 


RPC package. imitialize tasks ACCESS $0 nn esscsseesenesseesennenes rpcTaskInit{) 1-286 
initialize task's regisbers. .ssnsssssseccseessee taskRegsInit{ ) 1-403 

IMitialize tebmet AACTION. as cnsecersencssccssccsreeeeennes telnetinit({) 1-444 

Imitialize tty CEVICS ene n menses caer ennssenencennennesnes tyDevinit{) 1-466 

fields in SBIC structure. initialize user-specified ...............— wd33c93Ctrllnit{ ) 2-31 
semaphore. create and initialize version 4.x DEM ATY .-nsennennneennsenneen semCreate() 1-336 

set shell's default input/output /enror fds. .nseeesseee shellOrigStdSet{ ) 1-341 

device. issue INQUIRY command t0 SCSI ons ceessseeessssesesnee scsilnguir ) 1-308 

display specified number of instructions. disassemble and 2. neveevrecrrernerree K)—-1-31 
Internet address to long integer. convert dot notation 1... inet addrt )+1-140 
Absolute valise Of ibe ger. ws.sssssssscsenuecessensnseseeesesesennnenssntstentennenenseseeseute abs{) = 1-1 

read next word (32-bit inbeger) from SECAIN. .eennsseenssnecenssessseceecseeeeeennnsnnsenscs getuX) 1-380 
append word (32-bit inbeger) t0 Output StPOAIIL, —...-nsenvenenseecseccsennnnenecsscs putut{) 1-381 

look up host in host table by Inbermet adress. ss essensensenvseccesceeseeeeeee hostGetByAddr() 1-112 
address (host number) from. Internet address. get bocall ......essssssesecssecsccsessenenn inet Inaof{) 1-141 
return network number from Internet address. a nssensennssseerercssscssssssssrseessennreens BCL _Netof) 1-143 
extract netmask field from Internet address. 2.....eccscscsssnsseeeses bootNetmaskExtract{) 1-17 
Ethernet address for given Internet address. resolve ..z.................. etherAddrResolve(:) -= 71-72: 


and host numbers. form Internet address from network ................ isét_makeaddr() 1-142 
and host numbers. form Internet address irom network ::...<: tek suaheadde. A)" pita : 
routines. Intemet address manipulation =:. 
interface. get Internet address of networkiziiacesxeiz: 


point-to-point peer. get Scout ...*.. .. wiekaice 

integer. convert dot notation Internet address t0 LON, —..u.-..-scnuneesnnenenee tet addr) .1-140 .—... 
string to address. convert Intemet network number from acai -tnet_network{.)---1-145---: =~ - 

/all active connections for Intemet protocol sockets. — Fie ee OED . inetstatShouy ) 1-244 

connect C routine to hardware Mberrupt. .....seesessccesrsesineessneseeeseeessensnennnenscenes intConnect{) 1-149 

routine. restrict interrupt context OM USING a nnsenneeneenseseensen intRestrict{) 1-152 

determine if we are in interrupt context OF tASk/ a---seneeenmneene BtContext{ ) 1-152 

routine. construct interrupt handler for C ..................... ttHandlerCreate{) 1-150 

Set imberruppt bevel. anes seccsccceseceseccseceseeees intLevelSet{ ) 1-147 


language routines. interrupt library assembly —_.-___.- intALib 1-147 
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user-defined system clock Inferrumt routine, eae eee xsrClock{ ) 


interrupt subroutine library. Siete ects RU GD 

interrupt-level output. ............. tyITx{ ) 

lockout interrupts. ......... it eccates intLock{ ) 

Camel effect OF MAL OCK. .aesenneannsescccocsceseseersenreennesnrenseennsreereenrecerren ENELENIOCK, ) 

find I/O device in device list. 2 nencenneueveeee S08DEUF ins ) 

Erste 1/O Graver. once escsesesensseneeeeeeneeeeessereesseereeerreereeeees SOSDrvlustalX ) 

TOMWOVE L/O river, ccs nsscssseeesnscseereeeerscssseerresssessrennees SOSDYVRemove{ ) 
Network File System [/O driver, 22. sssssssse--sscscccsesseccssccesssssnesseensesesenensessenreneese nfsDrv 
pepe 1) O Geir rs aici a ete ties eam pipeDrv 

network remote fle 1/O river. en snvnsansscsscscsccessessssmsenennnncccscecnseegeeeet enone netDrv 

T/O irnberface Bara. nen ennenesseessessccessenseensseerensssensnnensnsoe ioLib 

Standard I/O) BDGARY sic esses cesses etcrenrsectlaastieceaelatiys stdioLib 

fowmmatted. 1/ O) BAR 2 sssscccscasces csacsdascecataserssciasassecttaseorancainconsice fioLib 

Ethemet raw I/O routines arid WOKS. 2..scsssssecsscsssssncscescesscsecsensen etherLib 

initialize floating-point I/O Support. —...sssscscsssssecesscscscenseeesesesssensenssee floatInit{ ) 

Ty OS StI sees icscsceaceh tt score Dan wanes KOSLID 

Ameifializee: T/ O SyStennn. a acesecescsccscscecwcistecncssasinsscicnconssscescenanbensenssonsen iosInit{ ) 

Ad device to T/O SYSHOM. ...-sesssessscssecsseeeessessseesssssnseseeeseennneesee £05 DEVAAA ) 

Gelete device from 1/O system. .n.....sssssscsssssssenennensnssssseessseeseese iosDevDelete( ) 

JUMP Program SUPPOTt TOULIMES. ..eessseseeereesne wweeeee PicLib 

associated boards. show jumpering of target arid assssssscscsscsseeccssesscersnnsoesee jump 
WUEANZC KOTO ies cscs elect snes nearasseadeee kernelInit( ) 

_ task management routines for kemel. architecture specific —.......sssssscosee taskArchLib 
management library for Vx960 Kermel task nn sssnssssscccssscssscssescescsescesseesseesssessesssseeeenes tASKLiID 
ANNOUNCE ClOcK Hick tO kerma) nn. weecsacescsesscccseeesneesconseccseescnssssccenmeceens tickAnnounce{ ) 
Vx960 ermel LT ary. ..........scccscscesnnnennemnsseneeneenseemnene KeMEILIb 

Feturn kernel revision SHIN, ....es.cseeeseesseesscoenee kernel Versions ) 

Set value Of Kernels tick COUMBCR. ...sc.sssewvseccsscssessssersenscessoosenssesseses tickSet{ ) 

get value of Kermel’s tick COUMWER, ...ccseroesossscssscssemnernserseseessorsensneeees LICKEL ) 

i driver. LANCE Ethernet imber face .....sssecssssssuneecsseeseseesten weees fin 
| Tea Time with Hime-editing, --...-seecscocscersenseseessorseersensesecnsenenseetee wwe bedRead ) 
Firne-ecditinig HIDr ary. .e-eeosesssessccssccceceesrnnenessssenensnscnsens .--. Ke Lib 

library. doubly linked list subroutim]e ...ssssscscsnennesnsececesesccsonssenseneseee IstLib 

find 1/O device in device Hist, i eneecenenneeneereeeeeeneeneneeneeneesene tosDevFind ) 
CCA. TNO WOH NA OE SE sal cass cats ece ales IstAdd{ ) 

TepoOrt muummber Of modes i Fist, nn eesneesenensseneesneecnscncnsscccesccessesseesnenstnnsseessnaseneese IstCount{ ) 
Gelete specified mode frm Fist. nsssseecesncsssssssesenssessessssscossceesoeesorseentsnssnesennseonees lstDelete{ ) 
extract SUDIist from Fist. a. --snssscscccovesscocesonsneeesconscnssceesecnesnnvenseseeseeee sees .... lstExtract{ ) 

frricd farst node my 1S 2a aoe teres eo at IstFirst{ ) 

and retuum first node from list. debete a savewvtessssssssesnsonnseenensensseneesenenenesenenten lstGet{ ) 
firvcd Last rhe tn TS sa cece cas oe eenSeatiweaeciecdseemacaes IstLast{ ) 
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find Nth node in Hist. cece snenneenenenneneereennereeeneeeneenrereenennenen SENHA ) 


find previous node ir Fist... ccenecsssscceseisseesesereseacsnsneeemineneessscrmcreesrecaees IStPrevious ) 

Farid mode i Vist. nasa sssssenssonessnerenesensnesseserscnsecseessssrenntneresessesesrcrses ISEF INNA ) 

Free 1a TSE sscssansinsnsnnsdessicanrapeschonensncnesttvrtcoeacecninsnssnisesansssceces EGEEVECEL ) 

node to select{ ) wake-up list. add wake-up 2.0... -------------0...... SEINOdeAdd ) 

all tasks on select{ ) wake-up Hist. Wake Up .....--ws-ssecensesesseneeeenseeeeneneee SEIWakeupAlk ) 
and delete node on wake-up Hist fir ....ssnsssssccsccesseceseeeeenneeee nana. SEINOde Delete, ) 
initialize select{ ) Wake-up Vist ..neseesssssssssesescsescssneseeseesseeseeese _.. Sel WakeupListinit( ) 
of nodes on selec ) wake-up list. get number ...._._......... sel WakeupLisiLen{ ) 
insert node in list after specified MOG]. ase ecscceneeccsscessseesee IstInsert{ ) 

Hist all system-KMOWM GEVICES. sean ananscsnsenensnneneenne devs{ ) 

Hist combents Of direCtOry. ..cccccsecsocsscsensessuesneutnsseneensee Is( ) 

or rsh directory. list comtemts Of RT-11, ftp, nn easeneesesneeeseessssssenseresseee lsOik ) 

Initialize list GeSCriptoe. —.seeeecesnssesneeeesesessersereenssveeesecersensnsereenesen IstInii{ ) 

list lobal SyMDONS 5 iennesesese atta, TksgX ) 

/string with variable argument list in specified buffer. ssn meececeescesennenntcocseees vsprintfi ) 
from specified node. find list node nStep Modes AWAY se. -esccesseassscseccecsseees IstNStep ) 
get list of active task TDs. i nenssnnnecsnerane taskIdListGet{ ) 

display list of devices in SySter. ...scs--enscssssecesen tosDevShour ) 

display list of fd names in SyStem. 1... seseen iosFdShow ) 

timed. clear list of function calls to be ~..-» timexClear( ) 

timed. display list of function calls to be ................__._... timexShow ) 

display list of system GLIVETS, ..-sewseceeseseneseneeensen iosDroShouX ) 

show list of task create routines. .......... haskCreateHookShouX ) 
blocked on semaphore. get list of task IDs that are .sassensecceseseececoceccennsseee semlnfo( ) 
task. get list of task variables Ob ee ennsneneseceseccseees taskVarInfot ) 

to SCSI controller. list physical devices attached ..._.__._._...... scsiSkouX ) 

doubly linked list subroutine bibrary. -.ssssscsssccseccsccesecseseeesseeeeeeseeeneeete IstLib 

near given value. list symbols whose Vales are eases ees enseteeeeee [kAddr{ ) 

/string with variable argument list t0 specified fd senseccsccesseescecsecceeennnnenesee vfdprintfi ) 
/string with variable argument list to starearc Out. ee enen ns ete teen nnn uprintft ) 
eoneabemate CW TSE ascites acti tse cecal IstConcat{ ) 

memory. load object module M60 ....seneennteeeernneen loadModule{ ) 

memory. load object module ito ...........-n...1... loadModuleAt{ ) 

MeMoOry. load object Ode WO senna ana sess ld ) 

Object mide «Wa her ates hse atic loadLib 

from Internet address. get local address (host number) ..................... inet_Inao{ ) 


TCB.. move i960 local registers from stack to ......... taskRegsStacKToToH ) 
stack. move i960 local registers from TCB to ........... faskRegsTcbToStack ) 
lock access to shell. weenie SHHLOCK ) 
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Log in to remote W06t, nsassscscecscrsnnsensesvenseersserreserseone MOGI ) 1-272 

log out of Vx960 system. .... were, LOQOUE ) 1-510 

Vo Fo MD 0-201 1-9 + logFdAdd) 1-196 

Set primary Logging fd. nana nnnncnennrenenees bOGF ASCH) 1-196 
Gebete Moggi gy fa nn aeencnsnnsseveeeeoresnesernerserrmenersnreoes DOQF AD lete{) 1-197 


message logging 
initialize message logping HDTATy. ..--snseeereseensneeeseerernremmearnreereeeees LOGIN ) 1-194 
Vx960 remote Mogi GAMO nanan sneeeecseeceserreerrsemneeererreeerrsermeenene MOQINA ) 1-271 
initialize remote login facility. ........... seeseseeeseeeeerseneseneereeeeeersnees PLOT NE ) 1-270 
Temte Login Bary. ....aanenennecerneseeeereseeeserereeesreensensmenmneecemeees MOQLED 1-270 
entry. display login prompt and validate user ............ loginPromp#{) 1-208 


Change hogar Stig, nanan aanann nner ens nnn rns loginStringSet() 1-204 

Initialize login tabbe. ..n.ssscsscsscccssccosecssccessecsecesceesceeeneeeeseeee loginInit{ ) 1-200 

Add user to bogin tab be. 1 aeeseeesseesseeessesseessnssneeeeesseenennes loginUserAda&{ ) 1-200 
delete user entry from Login table. on. .cessecscscessecessenssessneneenenenseen loginUserDelete{ ) 1-201 
display user login table. .....csscssessccssssssssssssssssnnecessenseenee loginUserShouX ) 1-202 

user name and password in login table. Verify... .cssccsscsessecesssensssensee loginUserVerifi ) 1-202 
EINE VXGGO DO 5 sciatic tad cecalca ctaccsccertstslasasetasntarncee .. printLogo{) 1-510 

Print Vx960 marital Crdries, .:....cescceeseeeseeescnesseuscensceeesscensresneesccces vwman 3-10 

Set signal: Mash isis secs aneeacecctee abe sigsetmask{ ) 1-347 

get subnet mask for network iberface. .-nscccsscccsssceeessee ifMaskGet{) 1-120 

Controller (SPC)/ Fujitsu. mb870B0 SCSI Protocol ...ssccsseccsscesseesceceeceeseeesees mb87030Lib = 2-1 
create control structure for Mb87030 SPC. .nenmssscssssscssesessccrseceseonee mb87030CtriCreate{) = 2-1 
control structure for mb870G0 SPC. initialize ..........see mb87030CtriIInit{ ) 2-3 
display values of all readable mb87030 (SPC) registers. .....s:csssccssennnensssneeeee spcShou{) 24 
Teport mibuf Statistics, .vvovvsccssoocsceerseececeesseesseeessenen mbufShou() 1-245 

Joad object modutle ito MOM Ory. eeneneansesscssssssccccccscescorssssseoneenereececsseeeeene loadModule{) 1-188 


- free block of memory. eee eee ee free{) 1-226 
reallocate block of memory. Sa Gad apd saa a 1-226 
a POOL Yo PIT nn 
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add memory to memory partition. ..._._...-.-. sem PartAddTaPool ) 1-220 
set debug options for MeMOry PartitION. ...-a-r-eeesaene. MmemPartOptionsSet{ ) 1-221 
add memory to system memory partition. neeieneneaeh ere as 1-224 


log formiatbed error MOSCA ge. annnnssncsscssesssscsessensesnseess logMsg{) 1-194 
receive message from message queue. ................... msgQRecetve() 1-234 

TeceIVe message frOM SOCK. a. nesnsscscseescee sees mnneeesseene recufrom{( ) 1-356 

TeCeIVe message from SOCK]. na anssscsessnseseeseeesensene seen snes recumss{) 1-358 

message logging library Spee ceanee mn NEON ERO loglib 1-192 

initialize message logging lDrary. .—....--.cceenwneneeeeren lOglnit() 1-194 

Create and initialize message QUEUE. ae nnncssccosessccccsesseeescesees msgQOCreate() 1-231 

Gelete message QUCUE. 2... esscsesecsenneccsesesmmnennenrenress MISQOQDelete() 1-232 

SEN MeESSABE LO MESSARE QUEUE. ....sccsanssccceccserrsecececeesssennmccerceeeees msgQSend{) 1-233 

TECRIVE MESSAQEL ATOM MVESSARE QUEUE. .nasnsenesnnnseccsccesrssseecscees sree eeene msgQReceive() 1-234 
number of messages queued tO Message QUEUE... BEE ease-csccessersenseeren msgQNumMsgs{) 1-235 
get information about Message QUEUE. ..-n-.cccscccssececcceseesseeseresssee msgQInfoGet{ ) 1-236 
Show information about message Quetse. ..ccsecseecsecceseecessesnneeeneeene msgQShout{) 1-238 
TNESEAV!] QUEUE HDT ATY. .-encseessevessevscccscecseccesecceceeseees msgQLib 1-230 

SEN MesGAage bO MESSALL GUCUE. .senvvneenseccssccerecseceeee msgQSend ) 1-233 

SEN message 0 SOCK... nvenccsscersseessecseeesenreenecerrssesessereee SENALOL) 1-355 

SEN Message tO SOCKEE. .....--avsecwscccsccessneesnseerteseessnnsssense sendmsg{) 1-356 

exported by specified host. mount all file systems ...--v-vsenenrenene fSMountAlK) 2-15 
mount NFS file System. .--.-cescesnssssccecssceseecsssessaeee PfSMooutt{ ) 2-15 


display mounted NFS devices, ..-----eesnnnee 1SDEvSHOUX ) 2-16 
create and initialize mutual-exclusion semaphore. Lm “1-334. 
library. mutual-exclusion semaphore + cere 

without restrictions. give mutual-exchusiot: SRRSEHELES Forve( 
| address. extract netmask field from Inteniét ..... boot NetinaskExtract{ ) 117 
attach bp interface to Met WOT. nn scsssnnensscessnsenseseecsccseesssnssseneesreesesseseeraneen Opt tACH ) 1-127 
information about backplane network. SOW orn bpShou{) 1-128 
attach emp inberface tO metwOrk. nn nsaacussssrescscecssersecessereesensensesnenseeseeesreeee NAL ACHK ) 1-130 


attach ex imberface 0 MetWOTK es ncscsesceesecescsssevescseseeensevcsconscecesnnsces sneer cesssce ene exattaclh({) 1-131 
attach In interface t0 MetWOEK. accancsacccesscneessenennneenuseenennnenenne bnattacht ) 1-132 

attach SLIP intberface tO met wrk. eaaaacscsesescccsssconsseesessescscnnsevenesseceecsseeneene slattach{ ) 1-137 
notation. extract network address in dot ................._...... inet_netof_string{) 1-144 

form Internet address from network and host numbers. .................... inet_makeaddr() 1-142 
form Internet address from network and host numbers. ............. iset_makeaddr_b() 1-142 
long (32 bit) from host to network byte Order... CONVELt ..--esssecesennseenteeeen htonl{) 1-392 


short (16 bit) from hostto network byte order... CONVELt .----nnanenenee. Atons{.) 1-393 
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Shirt GOWN Met wc COMME CHION. an encsaneneencscsnsennseeesecsseereeenreene SHMEAOWHN ) 
control to boot ROMs. reset network devices and transfer 


to ASCIL convert network dot notation address 2... Met _niOa_ BK) 1 


to ASCIL convert network dot notation address .................... Inet_ntoal ) 
driver. Network File Syston I/O) 22. enetnenenneeneneereeeeneees MUMBDrv 

Network File System Horary. 2. .--aco-----neosernee- NESLID 

initialize network host table. nssssssseenreneresrenrerrreeeens HOSET OU It{ ) 

get Internet address of network inberfac]. nan eneeneeenersensecrsssrerseereeee Addr Get ) 
set interface address for network inberface. a scsssnansnenssssscssseonserneerneneerneeee Addr Sek{ ) 
set broadcast address for network interface. a cccssncnvrenrvensecssesneee HBroadcastSet{ ) 


get broadcast address for metwork imberface. n.sennsceenevsseccsreeseenses ifBroadcastGet( ) 
define subnet for network interface. 2 anecceeenseeesscorssccsnrnserneneee FMaaskSet ) 

get subnet mask for network imberface]. an cscsseneennnnnnsenessesenscenssnsen ifMaskGet{ ) 
specify flags for metwortkk interface. ....esennnesscccssccsscessecesseessersseesnensee ifFlagSet{ ) 

get metric for metwork inber fac]... assscsesnnecevsesssscssesseescoesnnee ifMetricGet{ ) 

delete routes associated with network interface. nn aennssnsssseeenenrnenss FROUE Delete ) 
serial line IP (SLIP) network interface Given... ..ssossssssccosessssessccesesneeone ... if_sl 
change network interface flags. 2. -n..cssesssees ifFlagChange{ ) 

get network inberface flags. a aenevsunesanennsnnneone fFlAGGEH ) 

specify network interface NOp COUME. ....-ssccsseeesenennes ifMetricSet{ ) 

network inberface HDrary. .....ssesvecceeseeeeseenees seme ALID 

Met work inberface Wary. secs sessssscesenneenseneenecesees netLib 

display attached network interfaces. i eessnnssssssscssessssnsseereserrernsennes FSHOUN ) 
address. return network number from Intemet .................... inet_netof{ ) 

address. convert Internet network number from string to ............... inet_networkd ) 
IMitialize mMetWOTk Package. a aassssnsceeesenesenseeeneennene ... netLibInit{ ) 

display routines. network related] information a ssssccccsseesesen netShow 

install network remote file GIVEN. neces censsccsneecconssoeeseeeses netDro{ ) 

driver. network remote file 1/O) neneeevereernenrenrnreerrerenneees NED IV 

library. network route MANIPULAtiON es esns econ mnenneeesien routeLib 

print synopsis Of metwork rOUtiries, ae sanseeeenseneeeneeeennnneeneeess MAH ely ) 

display host and network routing tables. eens sscescseceeeees POMEESHOUN ) 
Initialize metwork SNOW FOUEIMES. aasscsecceseesreseseeeee netShow!Init{ ) 

met work task embry POmnt. ccc neeeeeenenseneneereeereeeeee MEL TASK ) 

convert long (32 bit) from network to host byte Order a, enentennennsnrersesrerresoneee MLOMK ) 
convert short (16 bit) from network to host byte order. ..w.w...sscerneneeee MtOhs( ) 
UNM OUNE NES device. a ncsscseccseeececnreeeesorseeneecsseneeeeeeees Hf SUnmount{ ) 

display mourtbed NFS devices... aa-cssscsnsesscsseccecssnsssnesnenecevecs ) 

irstaall NFS Giver, a asccsassssssccmnsevesossscneseeneeneee nfsDro ) 

mrourtt NFS fille SyStemn i. an sccsssansesssesnecsssessensesercececneeneneee nfsMount{ ) 

display NFShelp menu. .————_—_—_-- _. afsHelyh ) 

parameters. modify NFS UNIX authentication .......... sfsAuthUnixPromypt{ ) 
parameters. display NFS UNIX authentication —........... pfsAuthUnixShour ) 
parameters. get NFS UNIX authentication nfsAuthUnixGet{ ) 
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set NFS UNIX authentication —...................... frAuthUnixSet{ ) 

parameters. set ID number of NFS UNIX authentication 2.nasnensscsssnnrecscrene aneeeees ISLES EL ) 
node. find list node nStep nodes away fOM SPEC a neesesecenneconsseereenrens WEN SICK ) 
report number Of modes inn List. nnssncvoncesnsececcooreoscesessorsensernssersessessessserssnne ISECOMHE ) 

list. get number of nodes on select{ ) wake-up .............. selWakeupListLen ) 
[disassemble 1960 object COde.. ccsssancsenn-cscsssccenensessssssscreneseraenmnenreoeene AGNAIGO LH ) 


Object module boner. 2a nnnnnesssessscssosscsesscsscsescesseseeees loadLib 

Tetuurn current Offset i SECA. .escccsccenscssseccscconceesosenscensenccescneseenescaneenescses ftelX ) 

Open directory for Sear. .....sscssscs-sssscseseesesenne Opendir( ) 

driver-specific/ validate open fd ard return nn essessssscesssssneesrssssesseeeceenes tosFdValue{ ) 
,9, 5, 31 9 | AU eee OO ORT UUERU RO ne OmIDE Te Ete EE NnOOnSR Or operk ) 


open 
port bound to it. open socket with privileged —......cseuueeeee MESUPOTY } 


named file in place of open stream. substitute 2 eens eee encssenrnnenn PPLOPIA ) 

Open SHEA ON fhe. ccssasneseeseseescosevescvenssconscessnrsennnneessesess fowers ) 

bit) from host to network byte order. convert lomg (32 cscsesssnossscssssscccosssssnssssssceneeenene htonk ) 
bit) from host to network byte order... convert SHOrt (16 .........scssssceccsscsessecssssserseenseenseee ALONE ) 
bit) from network to host byte order... convert bong (32 ...sesecsesenenevrssssssssssareenseessente ntohk ) 
bit) from network to host byte order... comvert Short (16 ............cscsssscsssssssnnensesnesenerseee ntohs{ ) 
Invert Order of bytes in Buffer... ...ees.ccssccscesseececeesennnessssneee bisnvert, ) 

send packet on Ethernet interface. eset etherOutyaut{ ) 

to receive all Ethernet input packets. add routine .... etherInputHookAdm ) 

to receive all Ethernet output packets. add routine ............... ..... ether OutnutHookAsd ) 
CHEALE MEMO Y PaALtHOM ....-.csscccreccesesneeeeseccsennneessecnteeeeceses ent memPartCreate, ) 

Add MeMOcy tO MEMOTY PartiHOT. 0. neesnscsccesscsrsecsesenreeseeeeeeee MEMIPartAddToPook ) 

block of memory from specified partition. allocate 0... eee ccmnesnenenen ... menmPartAlloc ) 
set debug options for memory PartHGOM. nn anrescsscscescnsereessectscesereeene MCNIP ArbO pions Sex ) 
block of memory in specified partition, free 2 nsasccstesnnnesssssseetseesseeneen CMF arti ree ) 
block of memory in specified partition. reallocate 2. ccccssssseeseese memPartRealloct ) 
AAd memory 00 System MEMORY PaArtHTON. a escsenesssnseenessessescccesseerennnsetsecee memAddToPook ) 
options for system memory partition. set MEU gy cece sssssecsessecee mentOptionsSet{ ) 

of memory from system memory partition. allocate BOCK ...aessexssecesseesnnsseeseeeresen malloct ) 
free block in system memory partition. fired largest a esesesssssses sees wee MeinFindMax ) 
fields in SCSI logical partition. initialize... ......ss.sssseesenee SCSIBIKDevInit{ ) 

statistics. show partition DIOCKS ad 2s eeeeseeeseenee memPartShou ) 

show system memory partition DUOCKS arid | cevseeesssseecseessreeseenseseenems MUEMSHOU ) 

device. define logical partition on SCSI DIOCK ecto scsiBlkDevCreate{ ) 

get Current USer NAME ANG PASSWON,. 0. eseccsnesssnnersscceseeesseseeesesmeseeeveeeeeee remCurlaGet{ ) 

Set remote USEF NAM AM PASSWOTC, ..csnsecssnnnnsennssccssccseserconsnninenensreseeneeeen remCurldSet{ ) 

set remote user MaMe aNd PasSWOTd .sanenscscscenisccnensssssssesesssssessseeeceessensseeeseeesernne lar ) 
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Create RAM disk device. nce eeescscseeeen connor ramDevCreate{ ) 


default sasewcidenn ibanies loginDefaultEncrypt{ ) 1-205 
verify user name and password in login table. ........................... loginUserVerify{ ) 1-202 

Set clirment default Path, ...ccccccccccssssssesssssessesisessssieenen—eennnee SOD CfPathSett ) 1-166 

Set curremt default path nn -scscscccccccsescsscecsssssmuneensssneseesssesssessennenmmnenes HG) 1-167 

get current default pathy nn enneeseerrevercecssserseeesecsnceeeseereeee SOD EfPathGet{ ) 1-167 

get current hefault pathy, eune-veeceseccseeeseesssensennseenerneneeeersersesesernness SEECWA ) 1-168 

get current default pathy nn senaseocsccscesnnnsseeceessenseeeneersenessesencecsscsrnsnnees SELWA ) 1-168 
address of point-to-point peer. get Internet .....uiecsennnececsnenee HD8tAddrGet{ ) 1-119 
| Bet mame of conmected Peer. eeeeesunsencsessneeeenseenneneenssesnmensenssenuseneens SPtpecrname ) 1-360 
reports. run periodic task activity ................. wwwseeneeee, SPYTUSK( ) 1-365 

reports. begin periodic task activity ..-scccsccscsscssesesnceccanseceeceeeseces spy) 1-366 

spawn task to call function periodically. ......sccsccccssnssseeeseesesssenssnsneceseessenestee period) 1-485 
Call function periodically... .ssovmeccssecssenssesnnseeesseeeteesnnsseeseen periodRun{) 1-485 

CHALE PIPO DEVICE. neeacsssesennsarcscnnsesessnenersessen eee weer PRpeDevCreate,) 2-21 

Initialize Pipe CHIVET. n-nscccscccescosenseccscosseenssnsssesenneconseneenen pipeDr() = 2-20 

pipe 1/O Gniver sisson sees ... pipeDrv 2-18 

from task’s TCB. print complete information 2....nscsscsssssnnwecerccnsssnssnenscsessees t{) 1-491 
Girectory. print current Gefault a snsescscesccsseessonessesennssensee pwd) 1-496 

error status value. print definition Of specified ....-..-..nsecseeneee PrintErrno( ) 1-509 
specified fd. print formatted String 00 nc eeneeennsccssssesnsensesseeeneenee fdprintf[) 1-83 

standard error. print formatted SOI g 60 eens csseeeeseneeneeneesees printEr() 1-83 

standard out. print formatted String £0 .wesecseusenssessecessmenuee . printf() 1-81 

Stream. primt formatted SOM g tO nn. ssescecssesscsseceescnseeessosoees fprintf() 1-375 

variable argument list to/ print formatted string with ...____._-~ vfdprinth) 1-85 
variable argument list to/ print formatted string Withee sssssesseccssconsensseense uprintf() 1-84 
primt stack trace Of task. .ssusssscsecssssnescssrenetreereeseserees HH 1-32 

stack usage. print summary Of each task ’s .2..eennssnecoen checkStack{) 1-488 

TCB. print summary Of @€ch task’ s ..-ssssvsssnsesssccssoceacensccnsssssseeses X) 1-489 

TOULINES. Print SYNOPSIS Of MEEWOEK o.esnsencesnnscsnosessssccsesereeceeree netHely) 1-483 

TOutines. print symopsis Of SebeCbed ...sssenrsnvsceqescscccnsenesseseeeesen hel) 1-481 

from stack. i ey ar bcc career cor amas aie 1-458...... 

| : PTH VGGO LO. anna assess IE ale ELE esc printLogo{)~ 1-510: 
Sse print Vx960 manual entries. ...-.-sscnneicenennne VWinan 3-10 
: Information. print Vx96O VersgOn .ccscsccseceseccecereecsccseecesseenenescersreses .. version{ ) 1-492 
Change priority Of task. ..eseeneasssscsscscecsssenssoescoeue taskPrioritySet{) 1-425 

examine priority Of task... e-vscne-snnneseee taSKkPriorityGet{ ) 1426 

Change Shell prompt ...sssssssssccssssssccecssessnssesnsemnennserersnneee SEMPromptSet{ ) 1-341 

entry. display login prompt and validate User —..senssennensnen loginPrompt{) 1-203 
parameters. prompt fOr bOOt BM! nn.ssssssssssscoeens caine. 1-16 

pseudo memory device GIVE. ....-.cserecsseeseeeen 2-5 

Create pseudo bermmiral neces nnnessesssnnscccsceeseeee maaan 2-23 
pseudo-termrimal Griver. eens cessccsseessceteeneeneenee ptyDrv 2-22 

initialize pseudo-terminal driver. 2 nen nnserennn-- PLYDrY) 2-23 

2-26 


20 Intel | Rev: 30 Aug 91 


Keyword Index 


RAM disk Gaver iciicccicsussccubion ee ek ramDrv 2-25 

(optional). prepare RAM dlisk driver fon Use o..ucccssscsmecncecreecseseeeesnees EDEL) = 2-26 
library. raw DiOcK Gevice file SySbOM —.n.-s-scccscscssccesconseeees rawFsLib 1-254 

modify mode of raw device VOLUME. 00 .... Taw FsModeChange{ ) 1-260 

disable raw device VOlIME, 1... MQWFsVollnmount{ ) 1-261 

Ethernet raw I/O routines and 00k. 2 .nnnscsseonnnrneee QHherLib 1-68 

associate block device with raw Volume FUTCHONS, ens reccsenreeeee MAUWFESsDevinit{ ) 1-258 
prepare to use raw Volume library. 1 meneneeninn .. rAWFsInit{ ) 1-259 

POrIORM DUMeTed TOA assesses tieeslined asec aclenemrens frea&) 1-377 

if enc-of-file has beer read, Geter ee nena cece scssesssnecceneceseneecnncnceenee feofi} 1-386 
from input stream. read and convert Characters ssn ccsseeneenssenes FSCANA ) 1-382 

from standard in stream. read and convert Characters 2... .encnscsesseneneennene SCAN ) 1-382 
ead OUNCT cosacti thee endl areata: fioRead) 1-89 


device. read bytes from fie OF 2a. csnseccssccsnneeessteennserenseereons FORA) 1-164 
do task-level read for thy Gevice. 0 eeessesseesssecssscsmennnseessenmnonens LYRE ) 1-472 
read line with line-editing, 2. ensenwsescssessenneeneneee eMRead) 1-185 


integer) from Stream. read next WOT (BIDE en cacsceenenenscccesseresesccernntsenesscccse getuX) 1-380 

read one entry from GireCtOry. .ncesscccssensscesseeees readdir() 1-36 

SENSE command to device and read results. issue REQUEST ...................... scstRegSense{) 1-311 
device. read sectors from SCSTDIOCK .eseesseeeeeteenenen scsiRdSecs{ ) 1-310 

read String from fide. eee eens enssnvssneneccsecesseeeesnes fioRdString() 1-89 

read string from input SHCA, -.....esessseeensesessssnnnees fgets{) 1-373 

Stream. read string from starvdard 1 ....esevsescsccesssssmnseceessensree gets() 1-379 

Set file read /WIite POMEL. ..sesnscsnsccescccssceeserssseesssnssuneeseensseees Iseek{) 1-165 

notify rawFsLib of change in readly Status. ......sssssscssscssseeenneeeseees rawFsReadyChange() 1-260 
notify rt1 LFsLib of change in reacky Status. selesweveecrenseneeneeueene rt11FsReadyChange{ ) 1-296 
notify doeFsLib of change in readly status. .....sscsscscsscesessssceeeseeee dosFsReadyChange{) 1-58 
Check if task is reachy 80 run, nasensssssscscssecssrssecececceceseesnsneesecs taskIsReady{ ) 1-434 

| reallocate block Of MEMOLY. .-enveunnsenenrenncnen POAO() 1-226 


specified partition. a ee ee 1-222 
add routine to be called at reboot. ee 


reboek support Weary tithe Sec ates ste __ reboot ib 
packets. add routine to receive all Ethernet input ............ etherInputHookAdd ) 1-70 
packets. add routine to receive all Ethernet output ......... etherOutputHookAdd) 1-71 
TeceTve ata from SOCK... nsescvnnscccovecscorsssesonsscnssscescnsssoes rec) 1-357 
queue. receive message from MESSAPE ..... +... msgQReceive() 1-234 
TeCeIVe MESSAGE ATOM SOCKLE. aasnecsecesscessecseeneen recufromt) 1-356 
TECEIVE MESSARE ATOM SOCKEL. .n.aensscccssccesecsecessecenee recumsg{ ) 1-358 
return combents Of PCW Te gisten. ciccicccatss sh teccietiecetereee seca aecleeacicacatenic peu{) 1-507 
Tetuun COntents OF TCW register, ....-vsccnscscssccsessssssseeneeseneresseeceeneernsseeeseeetsnescene sens neee teu) 1-507 
petumn: Comberts OF ACW) reer stet ssc tics chcarrcaceesSosecaencsccocnnonnces cob cata inisceoboe acu{) 1-508 
r3-r15,/ return contents of register pfp (also SP, Tip, .....-..sssscesscsseeusseesennersneenssenstnnte pf) 1-506 
IMitialize taSk’S TEQISLETS. w.sneavecceesenneeneennnenssennenee wanrenereeneees LaskRegsinit{ ) 1-403 
display contents Of task’s registers. .-..ccsccccccsssessserecesecestenseeces taskRegsShouX ) 1-405 
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of all readable wd33c93 chip eit Gisphay VaWreS en arneene-cnseocserreseeceeeees SUBCSHOUK ) 
of all readable mb87030 (SPC) registers. display abies a ceseesnsoocsscceseeneneee SPCSAOU ) 
| move 1960 local registers from stack to TCB.. .......... haskRegsStackToTc( ) 

get floating-point registers from task TCB. ........................ fpplaskRegsGet{ ) 

gettask’s registers from TB. -.n-asssa-rssenrssssenromnnneeees baskRegeGet{ ) 


move i960 local registers from TCB to stack. .......... faskRegsTcbToStack ) 

display floating-pomt registers of task...» JppTaskRegsShouy ) 
set floating-point regishers OF task. a-axxence-nnvecessesoensnennne fp TaskRegsSet{ ) 

remote COMMAN Hrary. a s-sseeecssseesseeeseenees EEANE 

create remote file Gevice. nccnccnncncnnswcsenenue netDevCreate{ ) 

install network remote file Ariver. ns nscsseneesssnsscsnesessossscneess ..... NetDrv) 

network remote file 1/O driver. i. nsccsssssssoesseeecssessees ... netDrv 

Jog in tO remote FTP Server ..csssassssecssssnsennnsecsscssscersessesesee ftpLogin ) 

exported file systems of remote host. display. --ace-secesuenne nfsExportShouX ) 

Jog I tO TEMObE NOSE. ee nnnenconnsessccsaceecceenceceeseecesnnessenseeessnnneneenee ..... logit ) 

display current remote idhentity. --.-ssssssccnnseecsseenssnneenssenenn whoamid ) 

Vx960 remrote hopin Caen nn. nsensssccsscennnnsecssnseseseessee .. Plogind ) 

Initialize remote login FACHILY. ...ns-nuseseocececsecesereseceenseee .. rloginit{ ) 
remote bogin library. -avvansscccsccescseemnneen . MogLib 

execute Shell command O71 remote Machime.. 0... asesnsnansnsescsssccscvvescoseveecccsneescnnes wnneeeeees PCN ) 


set remote user name and password. ............... remCurldSet{ ) 


set remote user name and password. seessictespateccessestseses WANG ) 

TEMOVE CITECEOIY, ...senascneonesscsseonsv sree cessor sresnnescsen toes .. rmdir( ) 

POMOVG fe ss sass a ees ee ann PH ) 

remove I/O driver. ---s-sssscnsssoseene iosDroRemovel ) 

table. remove Symbol from SYMDOI ..-..se--sseeseeee symRemove{ ) 

task, remove task variable from -..s..ss.-sssscosoon taskVarDelete{ ) 

disable task rescheduling, sans asssesvsssrtenscsenererrenercerrereeee LASKLOCK ) 

enable task reschedule, ...ceansencinsssessssesseneececnecsseeeeseee taskUinlock ) 

indicators. seaet ete uadlen oe Ale pagent tain as ........ Chearerr{ ) 

transfer control to boot/ reset network Mevices AI .neavssnsnssonecsssereseen _... reboot ) 
directory. reset position to start Of scsi PEWINARIN ) 

pulse reset signal on SCSI DUS. 2 aneesesnnnnennes scsiBusReset{ ) 

TEStart CASK. sec nnnrevererrseenseessccesscecsseeeenrseerseerreenee LASKRestart ) 

resuinie (ask: ss se sete taskResume( ) 

TOSUING (ASK cick i ete ee) 

Create empty rimag buffer. eeaeencssenscsssennssceesseerseoresnsssesnensncesen rngCreate{ ) 

Gelete ring bunffer. nea asec eecs eens ences PDE ) 

get characters from ring buffer. assess ecccsencnecsceesncneneneene rngBufGet{ ) 
put bytes iro ring buffer. a aaeaneenes anes nemeeeereesteenenesen rmgBufPut{ ) 

number of free bytes in ring buffer. determine ~............................. mgFreeBytes{ ) 
determine number of bytes ir. Ging buffer, assesses cove eneeenseennn nemseeenenenescss rngNBytes( ) 
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make ring buffer empty, nea nenn anne MGFLUSIA ) 

test if ring buffer is empty. 2 -..nsensennee IsEmpty ) 

room). test if ring buffer is full (MO MOTE eeeeseeeere 

Hibrary. ring buffer suber outime naan eseeoeeesseeeseesenecsnseseeeseesees 

ring/ put byte ahead in ring buffer without moving ~................... mgPutAhead ) 
advance ring pointer by n bytes. ..............--..... mmgMoveAhead ) 

in ring buffer without moving ring pointers. put byte ahead ~.................. mgPutAhead ) 


generic ROM initialization a eancoseenerececseeeeseseennee POMStare() 


ROM initialization module. ... bootinit 

boot ROM subroutine brary... DOotLIb 

Module for bOOt ROMS. Systerry .n.ncenecccssccssenscesseeecsseseneceseennseeees bootConfig 

and transfer control to boot ROMs. reset network devices Te ENT reboot{ ) 

TOOU CASK sss os ee usrRoot{ ) 

enable round-robin Sebection, 2. aansecnsencsccoseees kernelTimeSlice( ) 

PUN DO i coca cacitant cia eines eho routeAdd ) 

MOIS TOU ii es es ec eee rosuteDelete{ ) 

network route manipulation Hbraxy, eesenvennsecccscccseceeeeesen routeLib 

display host and network WROULGRI AS CATS sec ceases routeShou ) 

RPC package. .enceevenveseeseesnenesntnnentnsensnnsntn rpclnit{ ) 

Initialize task’s access $0 RPC package nn.-e-as-cccsnssscessesnssseeeeesseneseeseenes rpcTaskInit{ ) 
RPC support Br ary. ann nnnsccseeessecesecesscessonteneeneccs 

initialize RT-11 device Gescripton. ....cseeeeeneene r£11FsDevInit{ ) 

initialize device and create RT-11 file systerm eu .scscsccceeseseeeeenneenteeetes rt11FsMK{fs\ ) 

list contents of RT-11, ftp, or rsh dine ctOry, es nns---vsecssennseecessseorerveneee SOMA ) 

Prepare to use RT-11 Bbrary. a annseevemnonsccceseneeeerneneneee ... #11 FsInit{ ) 

system library. RT-11 media-compatible file -._._........... HtLIFsLib 

modify mode Of RT-11 VObume, .nccsesnvmresesseeeenn ... 1#11FsModeChange{ ) 

fragmented free space Or RT-11 volume. rechaiimy sees nocsceesessecesseerseeeeseeeenese squeeze ) 

make Calling task safe from Gebetio1e ..seca-cseeccesssscccccececeessecseecesseesees taskSafe{ ) 


and partially initialize SBIC structure. create ................. WA33C93ChriCreatel ) 
user-specified fields in SBIC structure. initialize .............. WASECISC Hla ) 


define logical partition on SCSI block device. nn eensecsseeessenenneneee SCSIBIKDevCreatel ) 

Tead sectors from SCSI DIOCK Gevice. nn nneeensessscccesessececeeeerenesee .. SCSIRASECH ) 

write sectors 0 SCST Block device. nn n.nsnssasceonnseeeceeeesersrnensees SCSIWHESECS{ ) 
pulse reset sigmial Or SCSI DUS. ..nannssssscccsreescceeeeenees wweresseesernnenee SCSIBUSRESEK ) 

all devices connected to SCSI controller. configure ................. scstAutoConfigt ) 
physical devices attached to SCSI controller. list 1-1 ~~. ScsiShou ) 
TEST_UNIT_READY command to SCSI device. is8tue nn nsnneseee nes SCSITeStUnitRAyf{ ) 
issue FORMAT UNIT command to SCSI device]. ns enssasscecsesssccessnssscceneees ... scsiFormatUnit( ) 
issue INQUIRY command to SCSI device. nan cccninsenennunenenneensnennmae scsilnquing ) 

issue MODE SELECT command to SCSI device. as annesensessnrnenseanrennrneeree SCSIModeSelect{ ) 
issue MODE SENSE command to SCST device. a anseccsconetensennnenes ......... SCSiModeSense{ ) 
issue READ CAPACITY command to SCSI device. nse enrennseneee SCSIREAACapacityl ) 
Computer System Interface (SCSI) library. Small a nee scsiLib 
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initialize fields in SCSI logical partition, ewe. SCHIBUDevinit{ ) 
configure SCSI peripheral (example). .......-. us ScssConfigh ) 
structure. create SCSI physical Gevice ase--v-ceconee ) 
structure. delete SCSI physical device ..--1----cenn SCSIP ys DevDelete, ) 
structure. return pointer to SCSI physical device ........ ScsiPhysDevidGet{ ) 
Library. Fujitsu mb87030 SCSI Protocol Controller GPC) mb87030Lib 
wake up task perce in. Select ). ..-..--.cesecsssersssceseeerereensernerseeseeneeereererereeseeeeee SEL Waku ) 
issue MODE SELECT command to SCSI device. ....... scsiModeSelect{ ) 
UNIX BSD 43 select library. ............. ssossnsnsenneeneerrserseesreeeeee SCLECHLID 
iMitialize select( ) BOCA. ae sseannnnanesneseesseeeseeeseereseeneerecereeere. Sb CH nit ) 
add wake-up node to select{ ) wake-up Bst. ..essseeennenenseeee SEINORCAAM ) 
wake up all tasks on select( ) wake-up Hist. 2... SelWakeupAlk ) 
initialize select{ ) wake-up list. .......................... selWakeupListinit{ ) 
get number of nodes on select( ) wake-up Hist. ..-..--senewee selWakeupListLen ) 
Create and initialize binary semaphore. ...-.nscssccsscssccsscesssssuneeeescsecsseeseneseees semBCreate( ) 
Create and initialize COUMHING SEIMAPIOTE. ...-.ecesencusserssernsssceessscesseesneseeseatenees semCCreate{ ) 
SETVE™ SEEDING scans nas sasdistossnsssenecsecatabcoccecetaavis semGtve( ) 
CAKE SONIVA DEMONS sss sca vests vssttson casscsarebsrmannnercn sentlake{ ) 
Gelete Semaphore. 2nsnsnercssececocscecssccsscecssecssnensennsnessccoces semDelete{ ) 
unblock every task pended On semaphore. 2. anaseonnnsesneccseccesssnsecneceensnssverseeeee semFlush{ ) 
task IDs that are blocked on semaphore. get list Of a sssse-sscsnscsousensecessnsssen semInfo( ) 
initialize mutual-exclusion semaphore. create Arid ...-.eneesensensenee SEMMCreate{ ) 
initialize version 4x binary semaphore. create ard. mcsmeswenneneensnneenene semCreate{ ) 
initialize static binary Semaphore. .......sssssssssnsssscsnnseeesseoeseesssssernseerreeesresseeens SEMAINE ) 
available. take version 4x semaphore if Semaphore iS. ....-....ese--aeewseeeseen ...... semClear( ) 
take version 4.x semaphore if semaphore is available. .....cccsscssscceseeseeessneess semClear( ) 
binary semaphore Bbrary. oo .scccssssssssssssssecssecesenecsseeses semBLib 
Counting semaphore brary. -sssscccssceessssseeseeesseeneen semCLib 
general semaphore library, .-.csssscssccsmsecessscesseeceeeseeeeeeet semLib 
mutual-exclusion semaphore Hbrary, ..-....sccesscccssecssseeseerenmeenrereeeee SEINMLID 
version 4x binary semaphore Wbrary. ..---asenyeonsnnseoreerveneerersnee, SEMOLID 

give mutual-exclusion .semaphoré:without/icassomsnnes ssemMGtveForce( ) 
' SEI data £0 SOCK nna scsssncecsscnnensscensenennescssceeeee SEMA ) 
reply. send FTP command and get ......-...secsecson ftpCommand ) 
send message tO MESSAGE QUEUE. sso. msgQSend ) 
Send message 60 SOCK! na nescccssccscnseesnneesesser ... Senadto{ ) 
SEMA MESSALE tO SOCK. ...aneenievnsesererereneseseesereseeneees SEMAINSA ) 
interface. send packet On Ethernet -n--wenscccoseeseeeseers .. etherOutput( ) 
SON Sigtiall 6 task, sscscscsosesssoseressesenesssnereeeseessnsneceeeeecseees kill ) 
SEMA sigmral 60 task. a aensevvsscosssocececseeeeseessnsseevees sigRaise{ ) 
log in to remote FTP SOrver .ascssseseensssssssessesecnsesecnnsernsesnseensseesssessenseennerneeeceeees flpLoging ) 
ARPA File Transfer Protocol Server. ......ssssssssscssccsssosseunssnressnntennsensccoecseseeessennenes .. ftpdLib 
FTP. Server Gaemnonn task. o.scccsccseosesssessccsessseeneseoeeseonent ftpdTasK ) 


get control connection to FTP server on specified WOst, scascuencsascueeneo .... ftpHookigh ) 
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Glean up and finalize FTP server task, csscccccceeceunennaennnnnnneneneens fipdDelete( ) 


initialize FTP server tah. ccscssssemececseeseereenereeseerreereerreeneernseeseeeees EINE ) 
start shell ...... shellinit{ ) 

Bock A0ceSS 0 SEV sane sassannsssscscsscerssenmnenerecerseeessecornnsenmneennesssssssrsonss SELILOCK ) 
machine. execute shell command on remote eossscsnreeee TOMA ) 
shell entry point. shelk ) 

Shell Execution TOULMES. .a-seenneenwscccccserseerrerren SHelIL ED 

isplay (Or set) shell Histony. sv--.-v--seeseeernneeccsennneeererersmecrnresennne SHCLIETis tory ) 
isplay (or set) Sle] History. eeeseus.sssassconeseessoneeeennnsssresseeseensessenanssscceeesserssesee POA ) 
__ change shell prompt. shelliPromptSet( ) 


script. signal Sat casas ees 
SO MOY 205." Set Shell's default a -aaveneeoeeverenereneneeere SHELDOrIgSHAS CH ) 


shut Gown network COMMECHON. 2. esssseneces shutdown ) 
Sheep uur occurrence OF Si QTL ae snnnneesnsensevnseesescnsscceecensceeseccsscesenecenceseneesenneses . pause ) 
initialize signal facilities, nme enn SAGTHE ) 
software signal facility Hbrary. .....cscccscccccccssscesssessnsnesnnsesssee 
IStall sigrval harder. nc csssesseeeeneccscecereeseeesecessnnnnnnecsscccces sigvect ) 
SOE SATA LAVAS ccc ca cccasasncsensscoveemoennoceabcanen sigsetrnask{ ) 
pulse reset signal On SCSI DUS. .......cseernsnsesnseeeenrereees SCSIBUSReEset{ ) 
processing script. signal shell t0 StOP antennae SHE ScriptAbort{ ) 
Install separate Sigmal Stach... -sssccsscecssecssceessesmneeesenmneeseeenseeseee sigstack{ ) 


SENG Sigmrall 60 task, eeenensnasscscscceoscccsscceseensessceesererensssenssessceereceenes MILK ) 


SON Sigal 60 task osc cneneeennenersersssererrrererseereesessareeeennenn SHRAISEL ) 
add to set of blocked sigriads. .aceseonccccccsccseeeeneneneensesrsseeeesenecencsesssncsenessonnsens SEQUHOCKL ) 


SUM GIC-SLEP. ans evsaneseneeereoreenrsonsernteneeneeseennertnesnnnnmennneente s{) 

subroutine. single-step, but sbep OVEr savsecsscccesccsscscsccnsesssenmneccccces so( ) 

block. find size of largest available free... memPartFindMax ) 

signal. sleep until occurrence of ninninemnennne PAUSEL ) 

Initialize SLIP interface. asc sneneenevennnsenrenerssssrsenrsscsesscrsenrennees Sip rst ) 

set baud rate for SLIP interface. ES alpaat ) 
driver. serial line IP (SLIP) network interface Sn a teen if sl 
Dari mame to SOCK neeeaveenrennerescnresesrnercnsoernnneetnntenebenionsncereneorennncers DEM ) 

HDCT SOME asics sase caer csbcsemintorascacecncasntstsecss SOCINELY ) 

erable CONMECHONS tO SOCKEt. ne neavssscscscscssssceisorseninemnrreccnssseennseretsersennrenessernseneee HstEt ) 
ACCEPt COMMECHION FON SOCK EE a anneensanvsevcecovssccsssnsnerneceseenssneestnnanmnmnnmueccscccc ceessnaneces acceyt{ ) 
IMitiate COMMECHON £0 SOCKS. acsecennnecsnsennecseesessennesecssesseeneetsenescensenssrnmnscssesees CONMECH ) 
Send data to: SOCK EG cise oa cocci cere ncemutainmcemncoes send ) 

SEN MESSAGE tO SOCKE. seeessecssecsennnsseenrsnsnesenencececececeeenesensmtsnesseeeseeeeseeeeeeent sendto{ ) 
TECLIVE NVESSAG! FO SOCK nanan asec eens tnencrreveerreernerenenenenenees PECUPPONH ) 
SEN MESSAGE tO SOCK. --aanaseovenecseccescnncceeornseeensoneresereerseeenereneeeescenesnastee sendmsgi ) 
receive Gata from © SOCKEC. ciccceceiteie cei ee ce recu( ) 
TECEIVE MESSAGE FPO SOCK EE nc aaanseneseensccvsscneceeereeeeeenessessuenenatnnanenensseesseesssesseerenee TECUMSRL ) 
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UNIX BSD 4.3 compatible socket library. ...... sockLib 
Bet Socket mare. a nasscscceeeseeseneeeeeerssreneeeeeeeee QEESOCKNaMEL ) 
get socket options. nneeeeneee SEESOCKO YH ) 

bind socket to privileged IP port. bindresvport{ ) 


bound toit. open socket with privileged port ....-.escseseseee PrESUPONE ) 
SPAWTI ASK, 0n..n-nscoroererererereeeersererseerseressresssnnnnrernene LBKS pW ) 
periodically. spawn task 60 calll FU CHM 2 sseecsensoreeseseenneessesseene POTION ) 


repeatedly. spawn task t0 call Fun CHOW 2 cscsseeeneeeenssccerenneerreenee POPOL ) 

parameters. spawn task with defarilt a ncsesscecsssscecceeeneeonneeeseerreees SH) 

control structure for mb87030 SPC CROAte siesta b87030CtriCreate{ ) 
control structure for mb87030 SPC. imitialize 2. .sssscsssssesceneneene 9D87030C trlinit( ) 
SPy CPU activity LH Ary. aeeeenesevessecessccseccescesennseeseeeesseeees spyLib 

Stop Spying and reporting, anna mneerensnerererrennnen spyStop ) 

Install separate Sigmial Stak... ..asscssscaccessnennseneescensecececeeseeseeeneeeerensnecessensnees sigstack{ ) 

allot memory from Caller’s Stack. 2...ssssssssensssessssnssensnessnmnensnrrnnneneee LaSkStackAllot{ ) 
local registers from TCB to stack... move 1960 .aveccesssssessseesees taskRegsTcbToStack ) 
trace of function calls from stack. prirtt 2...-scccsssccssccscccssecseccsseseceeeeeseseesateonenesccss trcStack{ ) 
initialize task with stack at specified Address. 2... eennncewneccssoessernesssseee taskInit{ ) 

move 1960 local registers from stack 80 TB. ...ssevssscsssoneecssccecorneesseees taskRegsStackToTch{ ) 
StaCK trace HD ary. a sssnsesesennsesssccseccersennsensceeseseenner see trcLib 

rit. Slack trace OF task initio asics eect tt{ ) 

print summary of each tasks stack USage. .eenveccssesennsesnscseessessecscecssceenseeseeeen checkStack ) 
Print formatted string to staredard errr. an sannsssssccccscesssnnnensscceeecesesenvecereenseecs printErr( ) 
Tread string from standard in stream. .....ssssscscssccsscsscscesscesersseesoeeeesennsent gets{ ) 

and convert characters from standard in stream. read 1 ssnssscscesccosemecesecenesene scanfi ) 
return next character in staredlarcd in Stream. ces cseenescsceeveseccseneessccnevesesonscnnteocse getchar( ) 

get fd for global standard in/out /err0n. ..ssssneesccsseenesee ioGlobalStdGet{ ) 

set fd for global standard in /Out err. ..ssanenecssessennensee toGlobalStdSet{ ) 

get fd for task standard in/out /errOr, ees.cnsenseeesscesnnesceee ioTaskStadGet{ ) 

Set fd for task standard im /Out [errr .aeessesecsccesecssnssnseeen ioTaskStdSet{ ) 

Standard I/O BD rary. ssssssnsasstsseseernrenreerrrecrrenreeenene StIOLID 

bast print formatted string to stardard Out... .-nssssssscssscssssssesessssrescesrecenssemereesssnnee PINEAL ) 
a with variable argument list to starlard out. /Strityg, aeesceccsesecescsecusenserssoneseereen oprintfl ) 
append character to standard out stream, secscessncsensecneecsnecseneeeesnne putchar( ) 

SHow partition bhocks arvd Statistics. ese cscsssssssessscnsccssooenscenscses memPartShou ) 
memory partition blocks and _ statistics. SHOW SyStem 2. --1e-anevensensenreneeee MemShou ) 
GRAS poNy UE” SURERSEN CS ct a a hs caciscc sina .... EpstatShou ) 

report mek SCALES css Hastie ceri mbufShow ) 

Gisplay statistics for KOMP. eenennesnsssnseresseneecceeee icmpstatShow{ ) 

display all statistics for TCP protocol. i neecseessseecee tcpstatShou ) 

display statistics for UDP protocol. .................... udpstatShow ) 
buffering for either stdout or stderr. Set HINe ssssssssseseeenceseeecerseenenssscee ...... Setlinebuf{ ) 
initialize stdioLib support. en enreneseeereers nese stdiolnit{ ) 
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COPY In (Or Stir) t0 Out (OF SEOUL). ..n.ssscscsscneenseesenersnsessoescecssontnesenessesereennnutsnateneson copy( ) 
set line buffering for either stdout or stdert. ....nsssscsssssoreoseceneersensessenssereoene setlinebuf{ ) 
TETUM NEXt Character iN WpPUt STEAL —...ccsccececsseecenecseccssessonseessnnnenssessesenssseseessneesseceses fgetl ) 
Tead string from imput Stream. ......s.sssccscccsssnesssnnnssssssesecceeseoneesssessesesseusenntneteneton frets() 

Out any buffers on Output Stream. WHC a annnnscssccscessecesesscccssccensssecsneessessesenseente fflush( ) 
Print formatted string CO SHAM. 2. sessssccevscccssesceeeseccnssnsssecessosensesnnesenesssesssnneneeson forintfl ) 
append character to Output SETA. enn anccencnsenssecemnnesesssesersesssensesecesremsennnennesensenseee [UEC ) 
string to output stream. copy NULL-terminated) .---seseeeeeeeesee fpusts{ ) 

named file in place of open stream. substitute a cssessssscsseenecceneenen seen freopert{ ) 
TOP OSHION: SUCAIN oss es a cle eee foeek{ ) 

Tetum Current Offset i SEMCAIT. a nnnssesscsccarsssscscsonssssrusssssoesennsooesconsseenennssecsennseessuens sees ftelX ) 

read string from starndard i SUTOCATT. see ensssccesesennsssseseecscvesererennneccscnenssenesentscneesetsumennnescet see gets( ) 
word (32-bit integer) from stream. read Wert nese enenesseensevesnensneneeeeecennsnnnn cents getur ) 
string to output stream. copy NULL -termiinatedd 2... vscscssccensnsecee puts() 

(32-bit integer) to output stream. append Word ances eeenecenn nen putut ) 
convert characters from input stream. read and 2. ncsscccsesssessnseceeeseeeseeessseenee . fscanfl ) 
characters from standard in stream. read ard COmvert ...-ssssaenesscsscereeneeeseeneeneee scar ) 
specify buffer to be used O7 SHAN. ...cscscssessnssssscserssecessreseneessssssesssecsonmensssesssessssceceensee setbufi ) 
Set buffer to be used On SHOAL. 2. scesssssereesnnesconeenensennnscesscessensenssennnneensereeeee SEEDS SEH ) 

push character back into input Stream. 222. ssssscccesssccsecssceeseeecrsnt nuevas nnenennssensccsosscs en ungetc{ ) 
get fd associated With Stream. sce ansssscseconseseeseennnstnetennninnsuetsnntsnenennnennnnenessesss filenc{ ) 
next character in standard in stream. Petry occ eseanesssscscenssssncenssccecnsessnsssnsnencseneseeeee getchar( ) 
return next character in input stream. 2 cescceesesescenseeesscesnesseesnannsensennenseecssetenenseenssees geic( ) 
TetuN Next Character in MpPut SHAM. .2...necvscecscccsseceseccnseeececsscescessnennssnssnessnmecsecceeseeeeeesneees getc{ ) 
Character to standard out stream. append -2n.nsenesessesssenssessensnnetnnnnseeensees putchar( ) 
append character to Output Shea. 0s eneeesscceeeennnsnneesnnsmnenunessrenasnnnecesecesesed ent seet pute ) 
POsitIon stream at DEQITUUTR, ...ceesseesseesecsssseeeseesseescceseeesecessseeen rewind ) 

empty stream buffers and close file. vnvsssscsscesneeeeess frlose{ ) 

Open, Stream ON MG) tice eee es foper( ) 

ASSOCIAt] stream With fd. asssesssecscccsccsssccscecsseeremneveccenensceenee fdopen ) 

COPY from / tO specified, SETOAMIS. 2 cesseentenesentveseenseenecseetennsecesscnsseenentstnete copyStreams{ ) 
Tetuirn Kernel revisiOr SUING. ens nnnsscceesnssseseseseseeneneeeessentenrersessesecess kernel Versiord ) 
Change login String an anneneenesneeereeeeneseereeneeneneenteennntn loginStringSet{ } 

get task’s Status AS SETH nae nscsssscsesnessccennsseensennencnncnneseenes taskStatusString( ) 

COMVeErt format SEIT. snsenscccsscceensseesnsscesscesscessnneseesseessceneneessecs fioFormatv\ ) 

for arguments from ASCIL string. obstariry VAR UeS cesses eens eenscessseecseccennnnene sscarf ) 
Tea string fromm ibe. ca ene eeesnesssnceseeneerneenenene fioRdString( ) 

read string from input SOA. A eeseenecsssenecenssennsseseccscensee fgets() 

Stream. read string from starndared i ss assssscecncnneeensces gets( ) 

put formatted string in specified buffer. ss cscnetenesenee enero sprintf ) 

string subroutine Hbrary. na sceecccsceenseee strLib 

Internet network number from string to address. convert 1... inet_network{ ) 
copy NULL-terminated string to output Stream. .n.escsccscccecceseneeeee snes snccereenenenes fputs() 
copy NULL-terminated string to output stream. asa acess cece escecceseescees puts) 
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print formatted string to specified fb. assueneeeeecerseennmmneseeneee fprintfl) 1-83 
print formatted string to standard C2100. ---n0esneenennnennnnee INLET) 1-83 
print formatted string to standard out. —_________._----.---—. Pree ) 
Print formatted string b0 SCAM, nn nnnsnenesenesensrereereereresteerserrereeseseenees Sprint fl ) 
listin/ put formatted string with variable argument ~.......-........0...... Usprintfl) 1-85 
list to/ print formatted string with variable argument —.....-......-..0... Updprintfl ) 
list to/ print formatted string with variable argument — 0100 Uprintf{ ) 
define subnet for network interface. ..--ee YMaskSet{) 1-119 
interface. get subnet mask for NEtWOTK ...--..-0eessreennnnenee EMaskGet{) 1-120 


delete previously added task switch routine. .....cceeseenenene 


Look up SyMbol Dy Value... nassssnssssscesesessnneeessssness 


“create andadd symbol te syrinbol-table! =: 


lst global. symbols, list goal sym mole. | 
Make table Of Symbols. csc.csssscssnicecesesiseeseeszieeninunineensnnannanenesneeee makeSymTbl 3-6 

given value. list 7 tel adaaieeiaa eee eee IkAdar() 1-505 

host and network routing tables. hisplay i isisssssossnssssccecccescsesceeseesees routeShou({ ) 1-283 
takes Semaphore. ...seeveieesscssccsseennennnssseeeseeeseee seeseeneeene SENMM AK) 1-328 

semaphore is available. take version 4.x semaphore if... semClear() 1-337 
FIP SOnVer GACTIONY TASKS ois crests cecestesccietcssecscscaesincaarciecnrece ftpdTask{) 1-107 


up and finalize FTP server task. AM  ..secnsennnsseneeesensmmeeenreeersnmnsnnene fipdDelete{ ) 1-108 
Initialize FTP server task. .....ssssssssssssunennecssssessseseseseresssssssenseesssecesseessssseneesnnee fig sit{ ) 1-108 


MESSAQE-BOR PING SUP POut CASK nanan sesscneecentennneennenenstnnnsnestensnnnrennteennneeesseesscens logTask{) 1-197 
print stack trace Of (ASK istics casita tcc ascotieeseelanates wees KK) 1-32 
SOTA Sia C0 AG erst ceesecissccvosemnnsndoncecsecsecncbaanicnsobenccseorsamaentacs WLM): 1-349 


ser signal 0 task. cccsseeesiesnneuenenenneneaeeseneesntenenne sigRaise() 1-349 
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spawn. task taskSpawtn) 1-419 

NDE CASI esis estate ieee ee) 1-427 

eho Ck ncn cccsenrnnecscscscsemnerserseerresesenessnrsssnerearroreneeens LUSKDelete{) 1-423 

TRSUINC CASK. cscs neeessnseces . taskResume{) 1-424 

suspend task .............. taskSuspend() 1-424 

change priority of task ..... wee. baBKPriovitySet{ ) 1-425 
restart task. taskRestart{) 1-425 

examine priority of task. taskPriorityGet{) 1-426 

get task ID of running task taskIdSelf{() 1-433 
verify existence of task. taskldVerify( ) 1-433 

get information about tes. en acenessessececcconeccecessnscsnencennsnenecessnesseeetenes taskInfoGet{) 1-436 
Addl task variable to task, sce ssesesesseecsecssensereseeessonenecenccnnennecenneret taskVarAdd) 1-440 
Temove task variable frown task. cesses sovsccossvessccssuesnoeeesesssneecseeeeceestensncccs eet taskVarDelete{) 1-441 
get list of task variables Of task... .cccsessstecsenreeenscccseessseessest tees eenteeressceescense taskVarInfo() 1-443 
TOG tS nnn ean ncsescecsceconssconererteeeneccscnesenesenerennneerssesrsessseeee MSYTROOK ) 1-475 

FOSUIG CASK iiss on seco teen tr{) 1-490 

SUS POT CASK. iiss accasrctss ssipcestie ler emasssnis ian acess ... £5{) 1-490 

COU NASM iia ate aca t&) 1-491 


error status value of calling task. Bet a ..sscssocssscsscssssessenmnsesnneneeneersseessseeeee CFINOGEH ) 1-65 
status value of specified task. get Crr08 sinus. ctctinineisiiccininnn FMOOFTaskGet{) 1-65 


status value of specified task. set F700 -.wa-.ssscsessnssscsssesecesseeens a a 1-66 
error status value Of calling task. Set ....s.secioiiwessueunssessceseeeeseeseeesseeseeseeesseneees ermoSet({) 1-66 
floating-point registers of task. display iio nace ncceciumnee fpplaskRegsShouX ) 1-95 


floating-point registers Of task. Set .asveusscceceseesnneneenenuneees fpplaskRegsSet{ ) 1-96 
start collecting ina seseecessenensesseeseeeseersnnsseessersennevene SIYCTKStarl{ ) 1-363 


Stop Collecting task activity data. wescu-sseeseunswnsensnnnns spyClkStop() 1-364 
display task activity data, aenneuiinenren neem SPYREPOE ) 1-364 
run periodic task activity reports, ...W..W....0co pain anne SPYTash{) 1-365 


begin periodic task activity reports, veeieenennneenenntonnnn SPY) 1-366 
set task arithmetic control word. ............22.taskACWSet{ .) :. 1-406. 


we are in interrupt context or ek comet Seem a ee asia it. coc nt Content) = 1-152 ——— 
zo i has KcobiskIct(: AMIS 


show lst of task create routines. sh Cretan , 1-412 

routine to be called at every. task delete. add :.z..220.21.i...itaskDeleteHookAdM ) 1-414 
delete previously added task delete routiné-.::2.2:....:..:taskDeleteHookDelete{ ) 1-415 
et work task embry Pout .-nseeescoceecesseeeseeseeeeseenssenreecrsereneeee MOLTASIA ) 1-241 

Gelay task from ©xeCutinng ne anneeecsneesennecesssssenesccceeseeeee taskDelay{) 1-429 

task Wook Bor ary. sans seecsecseeeennens eeeene taskHookLib 1-410 

get name associated with task DD... na-soscscscesesscccssscssceseeevecenseensceesscesereesee taskName() 1-432 
Cr e710) ar.) @ | D ... taskIdDefault{ ) 1-434 

get task control bhock for task TD, nsannsssssscessccemsscsenssseneseeesceerenssensenerenmennsseens LASKT AAR) 1-435 
name. lookup task ID associated with task ................... taskNameToIa ) 1-432 
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get task ID of running task. enneneceneeeeneeeee LSkIASETft ) 
get list of active task TDs. ssssssceccsesceseeceeeesssereeseernersenreene LSKIAListGet{ ) 
semaphore. get listof task IDs that are blocked 01 .-ssssvenesnsnsnee. SEMITIGFOL ) 
check if task is ready to run. 
check if err 

Vx960 kernel. task management Hibbraary £00 anvaoesesscccconseereveenssee 
kemel. architecture specific pcr o eee ee 
display task monitoring help eM, aeaene-—nme SHIA ) 
up task ID associated with task mame. lOOK 210 neneeninnnsenreererrnne baskNameTola ) 


change ASK OP CONS. annem ha OptiontsSet{ ) 

examine task Optics. a aecsceeseseeeeeen ene taskOptionsGet{ ) 

wake up ee eR uosieaesa casera areascenlaes selWakeuy ) 

unblock every task pended on semaphore. ...--csssessecssecsccosecceeeeese semFlush{ ) 

set task proccessor COMO) WOT... .ssensesessseeee taskPCWSet{ ) 

disable task rescheullireg, ....-ssscscccssecscecescsseseessesseeeeseres taskLock{ ) 

enable task reschechuliryg. nes seesensnnnnsesssecnsnceseeeee taskUnlock ) 

make calling task safe from GebetiOn. a esevessnesssesneseceseseessensen taskSafe( ) 
get fd for task standard in/out /erm0r. -ressssseessssseceseees ioTaskStdGet{ ) 

set fd for task standard in/out/err0r. csc ioTaskStdSet{ ) 

routine to be called at every task Switch. Adhd .ecevensecsseccssccsseeeses taskSwitchHookAdd ) 
delete previously added task switch routine. q............0. taskSwitchHookDelete( ) 
floating-point registers from task TCB. get .---..ssccssccscesssecseeesseesseeeseeut fppTaskRegsGet{ ) 
initialized. activate task that has been ...ssscsssscnennensenssseeeeee taskActivate{ ) 
periodically. spawn task to call fUrction ...w..csseccssessscesssessessseessesssnnneeececoser period, ) 
repeatedly. spawn task to Call FUMCHION ..-sesssesusssenseesececececeeeseeeseeeseeeeeene repeat{ ) 
set task trace CONETO] WOT. ..cnsesesccccsenneceseeesee LaskTCWSet{ ) 

make calling task unsafe frotn deletion .......ssssssssccoseceeeeee taskUnsafe( ) 

get value Of task variable. essccsseeseersssennnsssnstsnnssenssssneenies taskVarGet{ ) 

Set value Of task Variable. .-ec-veccssensssccsseerssonensssnnecnnsensnne taskVarSet{ ) 
remove task variable from task. 2...cscscssseseen taskVarDelete{ ) 

add. task variable to task... sssseesssccssccserenseesesoes taskVarAdd{ ) 

initialize task variables facility. ......ssnseenssessssen taskVarInit( ) 

Bet list of task variables Of task. .snssessssseecssesseesseeeeeee taskVarInfo{ ) 

library. task variables Support --sca-ecsecone-cscsenneeenees taskVarLib 

spawn. task with default parameters. .............cssccesseseneen . 5 ) 

address. initialize task with stack at specified 2. ec--seneo wee tasklnit{ ) 
delete task without restriction. 2... nsseevesssees taskDeleteForce( ) 

handle task-level exceptions. seccssecssccseeeesermeneetene see . €xcTask{ ) 

device. do task-level read fOr thy a. eescsesesesssessssssseseescesecesssseneeen tyRead ) 

device. do task-level write fOr thy .esssesescsssssssssssccsecesseeseseeneet tyWrite{ ) 

initialize task’s access to RPC package. qu... rpcTaskInit{ ) 

Bet task’s arQUMe;ts. a acsscceseesseneecnseceeceeeees taskArgsGet{ ) 

Set task’s ArQumMe4nts. .ncnnvsccssccneeneessmeeeecee taskArysSet{ ) 

IMitialize task’s registers... naesesc-osevssccccoaceessccssnsneeesscs taskRegsInit{ ) 
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display contents of task’s registers, eweeewmnnmenenenes btSKREgSSHOUX ) 


get tasks registers fom TCB. —........... faskReoeGet{) 1 


print summary of each task’s stack USAge. aeansssnscscssenssseeeesssseesserseeres Che cKStaCK ) 
get task’s status as string. —................. haskStatusString{ ) 


Print summary of each task’s TCB. va----asscsovsneccececsseseenssessstunsnecssersreesessrrreccesarsseneses IM ) 

_ complete information from task’s TCB. print sean cae anessmssereessncseserrensseneners LK) 
local registers from stack to TCB. move 960 —.......-....... faskRegsStackToTan ) 
get task’s registers from TB. ..nccsscsssessccsesssenssernersconnseernmenececssnssenssannsennren PUSKRegsGet{ ) 
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do task-level write for thy Device. nnn acneseeeneesseseece eens snsnneottnerscerecennnne tyWrite( ) 
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parameters. modify NFS UNIX authentication aAuthlt “Prox 1) 
parameters. display NFS UNIX authentication .................. #fsAuthUnixShou ) 


parameters. get NFS UNIX authentication —.................... MfeAuthUnixGet{ ) 
set NFS UNIX authentication sfsAuthlinixSet( ) 
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get current user name and password, 1... PentCurldGet{ ) 

Set remote user name and password. n....cccsccscccseennensese remCurldSet{ ) 
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put formatted string with variable argument Hist 0 /  .encsceeseecscoseccssenenees vusprinth ) 
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